3.1.4.1.50 FAX_GetPersonalProfileInfo (Opnum 31)

  • Article

The FAX_GetPersonalProfileInfo (Opnum 31) method is called by the client to retrieve information about the personal profile (section 3.1.1) of the sender or the receiver of a fax from the specified fax message that is present in the described message folder. The Folder value MUST be one of the enumerations defined by FAX_ENUM_MESSAGE_FOLDER (section 2.2.2) except FAX_MESSAGE_FOLDER_INBOX. The ProfType value MUST be one of the enumerations that are defined by FAX_ENUM_PERSONAL_PROF_TYPES (section 2.2.4). The dwlMessageId parameter specifies a particular message and can be obtained using the following methods: FAX_EnumJobs (section 3.1.4.1.21), FAX_EnumJobsEx (section 3.1.4.1.22), FAX_EnumMessages (section 3.1.4.1.24), or FAX_EnumMessagesEx (section 3.1.4.1.25).

In response, the server MUST validate that the message ID is for a valid message. The server MUST validate that the client's fax user account has any of the permissions covered by ALL_FAX_USER_ACCESS_RIGHTS (section 2.2.83) enumeration. On success, the server MUST return the profile information about the sender or recipient in Buffer along with the size.

The client SHOULD free the returned buffer.

 error_status_t FAX_GetPersonalProfileInfo(
   [in] handle_t hBinding,
   [in] DWORDLONG dwlMessageId,
   [in] FAX_ENUM_MESSAGE_FOLDER dwFolder,
   [in] FAX_ENUM_PERSONAL_PROF_TYPES ProfType,
   [out, size_is(, *BufferSize)] LPBYTE* Buffer,
   [out, ref] LPDWORD BufferSize
 );

hBinding: The RPC binding handle for this call. The client SHOULD reuse the RPC binding handle used as an input hBinding argument for the FAX_ConnectFaxServer (section 3.1.4.1.10) or FAX_ConnectionRefCount (section 3.1.4.1.11) method call used to connect to the fax server.

dwlMessageId: A DWORDLONG ([MS-DTYP] section 2.2.13) that contains the message identifier for which the sender's FAX_PERSONAL_PROFILEW (section 2.2.44) structure is retrieved.

dwFolder: A FAX_ENUM_MESSAGE_FOLDER indicating the location of the folder in which to search for the message containing the personal profile information.

ProfType: A FAX_ENUM_PERSONAL_PROF_TYPES indicating whether to retrieve sender or recipient personal profile information.

Buffer:  A pointer to a FAX_PERSONAL_PROFILEW in which to place the returned recipient or sender personal profile information.

BufferSize: A pointer to a DWORD ([MS-DTYP] section 2.2.9) variable to receive the buffer size.

Return Values: This method MUST return 0x00000000 (ERROR_SUCCESS) for success; otherwise, it MUST return one of the following error codes, one of the fax-specific errors that are defined in section 2.2.52, or one of the other standard errors defined in [MS-ERREF] section 2.2.

Return value/code

Description

ERROR_ACCESS_DENIED

0x00000005

Access is denied. The client's fax user account does not have any of the permissions covered by ALL_FAX_USER_ACCESS_RIGHTS.

ERROR_BAD_FORMAT

0x0000000B

The message identified by dwlMessageId is an archived sent message and there was an error in reading the message file.

ERROR_INVALID_PARAMETER

0x00000057

The parameter is incorrect.

This error code is returned when any of the following conditions happen:

§ The pointer specified by the Buffer parameter is NULL.<122>

§ The value of the Folder parameter specified is not FAX_MESSAGE_FOLDER_QUEUE or FAX_MESSAGE_FOLDER_SENTITEMS.

FAX_ERR_SRV_OUTOFMEMORY

0x00001B59

The fax server failed to allocate memory needed for internal execution of this operation.

FAX_ERR_MESSAGE_NOT_FOUND

0x00001B61

This error code is returned when any of the following conditions happen:

§ The message identified by the dwlMessageId parameter is not found.

§ The dwFolder parameter is specified as FAX_MESSAGE_FOLDER_QUEUE, but the message identified by dwlMessageId is not an outgoing queued message.

§ The message identified by dwlMessageId is an outgoing queued message being deleted.

§ The message identified by dwlMessageId is an outgoing queued message of a different user, and this user does not have FAX_ACCESS_QUERY_OUT_JOBS permission.

§ The message identified by dwlMessageId is an archived sent message of a different user, and this user does not have FAX_ACCESS_QUERY_ARCHIVES permission.

Exceptions Thrown: No exceptions are thrown except those that are thrown by the underlying RPC protocol, [MS-RPCE].