3.1.4.1.73 FAX_SendDocumentEx (Opnum 27)

The FAX_SendDocumentEx (Opnum 27) method is called by the client.

In response, the server MUST initiate sending of the specified document to the specified recipients and MUST create the information for the fax messages and their message identifiers.

When the fax job is successfully queued, the server SHOULD signal an FEI_JOB_QUEUED fax event (FAX_EVENT (section 2.2.66)) to the client for each recipient by calling FAX_ClientEventQueue (section 3.2.4.2), and then immediately complete this call.

To succeed, the FAX_SendDocumentEx (section 3.1.4.1.73) method requires that at least one recipient and either a cover page or a fax body are present. Fax servers SHOULD provide a set of cover page templates to be used by the clients. In such a case, the name of the cover page template is sent on the wire during submission of faxes. Optionally, fax clients can create and use their own cover page templates. In this latter case, the format of the cover page template MUST be Enhanced Metafile Format Plus Extensions (EMF+) [MS-EMFPLUS], and the fax client MUST copy the cover page template to the fax server queue directory with a file name extension of ".cov" before making this call. The fax server converts the ".cov" file to a ".tif" using standard APIs for EMF+. The fax client can reuse the same cover page template for multiple FAX_SendDocumentEx calls.

 error_status_t FAX_SendDocumentEx(
   [in] handle_t hBinding,
   [in, string, unique] LPCWSTR lpcwstrFileName,
   [in] LPCFAX_COVERPAGE_INFO_EXW lpcCoverPageInfo,
   [in] LPBYTE lpcSenderProfile,
   [in, range(0,FAX_MAX_RECIPIENTS)] 
     DWORD dwNumRecipients,
   [in, size_is(dwNumRecipients)] LPBYTE* lpcRecipientList,
   [in] LPCFAX_JOB_PARAM_EXW lpJobParams,
   [in, out, unique] LPDWORD lpdwJobId,
   [out] PDWORDLONG lpdwlMessageId,
   [out, size_is(dwNumRecipients)] 
     PDWORDLONG lpdwlRecipientMessageIds
 );

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.

lpcwstrFileName: A pointer to a null-terminated character string that contains the name of the file, without path information, of the body of the fax in TIFF. The body file is previously copied to the server queue directory using the call sequence of FAX_StartCopyToServer (section 3.1.4.1.97) to retrieve the file name from the server, FAX_WriteFile (section 3.1.4.1.105) to write to the file, and FAX_EndCopy (section 3.1.4.1.15) to end the write operation. If no fax body is available, this pointer MUST be NULL.

lpcCoverPageInfo: A pointer to a FAX_COVERPAGE_INFO_EXW (section 2.2.12) structure that contains the cover-page information, including the name of the cover-page file obtained from the fax server with the FAX_StartCopyToServer call, if available. This pointer MUST NOT be NULL. If no cover-page information is available, the lpwstrCoverPageFileName member of the structure MUST be NULL. If cover-page information is specified, the fax server SHOULD use the server queue directory to find the cover page. The fax client can add a new personal cover page template to the server queue directory before calling this method by using the call sequence of FAX_StartCopyToServer to retrieve the file name from the server, FAX_WriteFile to write to the file, and FAX_EndCopy to end the write operation. If this call sequence was used, the client SHOULD set the bServerBased member of the structure to FALSE; otherwise the client MUST set the bServerBased member to TRUE. If bServerBased is FALSE, the server SHOULD validate that the cover page template specified by the lpwstrCoverPageFileName member has a file extension of ".cov" and the file name string contains (except for the terminating null character) only characters representing valid hexadecimal digits: "0123456789abcdefABCDEF".

lpcSenderProfile: A pointer to a buffer containing an array of FAX_PERSONAL_PROFILEW (section 2.2.44) structures that contain the personal profile (section 3.1.1) of the fax sender. This pointer MUST NOT be NULL.

dwNumRecipients: A DWORD ([MS-DTYP] section 2.2.9) that contains the number of recipients of the fax.

lpcRecipientList: A pointer to an array FAX_PERSONAL_PROFILEW that contains the personal profiles of the recipients of the fax. The dwNumRecipients member specifies the number of elements in this array.

lpJobParams: A pointer to a FAX_JOB_PARAM_EXW (section 2.2.14) structure that contains the information necessary for the fax server to send the fax transmission.

lpdwJobId: An optional pointer to a DWORD to return the job identifier. This parameter is used for backward compatibility with FaxObs_SendDocument (section 3.1.4.2.7). The fax server MUST ignore this argument if the fax client submits a NULL pointer value when making the call.

lpdwlMessageId: A pointer to a DWORDLONG ([MS-DTYP] section 2.2.13) that returns the unique message identifier that represents the fax message to be sent to all recipients.

lpdwlRecipientMessageIds: A pointer to a DWORDLONG array in which the server returns the unique message identifier for each individual recipient. The number of elements in this array SHOULD be at least equal to the value specified in the dwNumRecipients member. The elements in the array SHOULD be ordered in the same order as the elements of the lpcRecipientList array.

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 (section 2.2.52) or one of the standard errors ([MS-ERREF] section 2.2).

Return value/code	Description
ERROR_ACCESS_DENIED 0x00000005	Access is denied. This error is returned when any of the following conditions are met: § The limit on the number of recipients for a single fax broadcast was reached and FAX_ERR_RECIPIENTS_LIMIT couldn't be returned because this error code is unsupported by the fax client API version (FAX_API_VERSION_0 or FAX_API_VERSION_1, described in section 3.1.4.1.10). § The client's fax user account does not have the required access rights to submit the fax: FAX_ACCESS_SUBMIT (for FAX_PRIORITY_TYPE_LOW), FAX_ACCESS_SUBMIT_NORMAL (for FAX_PRIORITY_TYPE_NORMAL), or FAX_ACCESS_SUBMIT_HIGH (for FAX_PRIORITY_TYPE_HIGH), where the FAX_PRIORITY_TYPE value comes from the Priority field of the specified lpJobParams structure.
ERROR_NOT_ENOUGH_MEMORY 0x00000008	Not enough storage is available to process this command.
ERROR_INVALID_DATA 0x0000000D	The file specified by lpcwstrFileName argument is empty (has a size of 0 bytes).
ERROR_WRITE_PROTECT 0x00000013	The outgoing fax queue is blocked: The queue state is FAX_OUTBOX_BLOCKED as described in the FAX_SetQueue (section 3.1.4.1.90) method.
ERROR_NOT_SUPPORTED 0x00000032	The fax server SHOULD return this error code when the request described by the lpJobParams argument is not supported by the fax server.<152>
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned under any of the following conditions: § One or more of the following arguments are NULL or 0: dwNumRecipients, lpcSenderProfile, lpcRecipientList, lpJobParams, lpdwlMessageId, lpdwlRecipientMessageIds,<153>lpcCoverPageInfo. § The file name indicated by the lpcstwrFileName argument does not indicate a file of the expected TIFF format. § The lpwstrCoverPageFileName field of the lpcCoverPageInfo structure is not in the expected COV format. § The Priority field of the lpJobParams structure is not one of the following values: FAX_PRIORITY_TYPE_LOW, FAX_PRIORITY_TYPE_NORMAL, FAX_PRIORITY_TYPE_HIGH. § The requested receipt delivery types are invalid (the dwReceiptDeliveryType field of the lpJobParams structure), not DRT_EMAIL, DRT_MSGBOX, and/or DRT_NONE. § The fax server tried to return FAX_ERR_NOT_SUPPORTED_ON_THIS_SKU but the client fax API version. FAX_API_VERSION_0 (described in section 3.1.4.1.10) does not support this error code.
ERROR_UNSUPPORTED_TYPE 0x0000065E	Data of this type is not supported. The requested receipt delivery type specified by the dwReceiptDeliveryType field of the lpJobParams structure is not supported by the fax server.
FAX_ERR_NOT_SUPPORTED_ON_THIS_SKU 0x00001B63	The fax client module API version (described in section 3.1.4.1.10) is FAX_API_VERSION_1 or above, and the fax server is running on a version of the operating system that does not support the requested operation.<154>
FAX_ERR_RECIPIENTS_LIMIT 0x00001B65	The limit on the number of recipients for a single fax broadcast was reached. ERROR_ACCESS_DENIED is returned instead of this error code when the client does not support it (client-supported fax API version is FAX_API_VERSION_0 or FAX_API_VERSION_1, described in section 3.1.4.1.10).

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