<div class="content" name="FAX_SendDocumentEx" uuid="bac2e95f-f18b-448f-bb42-cc63b6ff04b2"><p>The <b>FAX_SendDocumentEx (Opnum 27)</b> method is called by
the client.</p><p>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.</p><p>When the fax job is successfully queued, the server SHOULD
signal an FEI_JOB_QUEUED fax event (<b>FAX_EVENT</b> (section <a href="26974d69-9306-4683-b4b8-23fda467e717" data-linktype="relative-path">2.2.66</a>)) to the client for
each recipient by calling <b>FAX_ClientEventQueue</b> (section <a href="c123443a-b672-4bce-ad30-50d2eb4d6cf9" data-linktype="relative-path">3.2.4.2</a>), and then
immediately complete this call.</p><p>To succeed, the <b>FAX_SendDocumentEx</b> (section
3.1.4.1.73) method requires that at least one <a href="46aba9c4-ebb1-4b10-86ac-4bb3025657b9#gt_53dfe4f3-05d0-41aa-8217-ecd1962b340b" data-linktype="relative-path">recipient</a> and either a
cover page or a <a href="46aba9c4-ebb1-4b10-86ac-4bb3025657b9#gt_222c82b4-c682-4c5d-b500-a6f0a7b96d4f" data-linktype="relative-path">fax body</a>
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+) <a href="../ms-emfplus/5f92c789-64f2-46b5-9ed4-15a9bb0946c6" data-linktype="relative-path">[MS-EMFPLUS]</a>,
and the fax client MUST copy the cover page template to the fax <b>server queue
directory</b> with a file name extension of &#34;.cov&#34; before making this
call. The fax server converts the &#34;.cov&#34; file to a &#34;.tif&#34;
using standard APIs for EMF+. The fax client can reuse the same cover page
template for multiple <b>FAX_SendDocumentEx</b> calls.</p><dl>
<dd>
<div><pre> 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
 );
</pre></div>
</dd></dl><p><b>hBinding: </b>The RPC binding handle for this
call. The client SHOULD reuse the RPC binding handle used as an input <i>hBinding</i>
argument for the <b>FAX_ConnectFaxServer</b> (section <a href="5cbfd38d-7a14-4560-ad24-9ed78f19a3bb" data-linktype="relative-path">3.1.4.1.10</a>) or <b>FAX_ConnectionRefCount</b>
(section <a href="a92941ac-bd07-4a71-af85-c2c157c97cf9" data-linktype="relative-path">3.1.4.1.11</a>)
method call used to connect to the fax server.</p><p><b>lpcwstrFileName: </b>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 <a href="46aba9c4-ebb1-4b10-86ac-4bb3025657b9#gt_eddadea9-c278-4d16-9279-f222df2cb735" data-linktype="relative-path">TIFF</a>. The body file is
previously copied to the <b>server queue directory</b> using the call sequence
of <b>FAX_StartCopyToServer</b> (section <a href="d4fdc04e-6594-4563-9700-d4cc645b4335" data-linktype="relative-path">3.1.4.1.97</a>) to retrieve
the file name from the server, <b>FAX_WriteFile</b> (section <a href="8ceb5261-3c18-4570-8b7d-61dcef50732b" data-linktype="relative-path">3.1.4.1.105</a>) to write to
the file, and <b>FAX_EndCopy</b> (section <a href="efdf1a1b-8f2c-450c-b6a7-36f115aa6ec3" data-linktype="relative-path">3.1.4.1.15</a>) to end the
write operation. If no fax body is available, this pointer MUST be NULL.</p><p><b>lpcCoverPageInfo: </b>A pointer to a <b>FAX_COVERPAGE_INFO_EXW</b>
(section <a href="ba8ddef0-c39a-45f2-88bd-789e1df67d86" data-linktype="relative-path">2.2.12</a>)
structure that contains the cover-page information, including the name of the
cover-page file obtained from the fax server with the <b>FAX_StartCopyToServer</b>
call, if available. This pointer MUST NOT be <b>NULL</b>. If no cover-page information
is available, the <b>lpwstrCoverPageFileName</b> member of the structure MUST
be <b>NULL</b>. If cover-page information is specified, the fax server SHOULD
use the <b>server queue directory</b> to find the cover page. The fax client
can add a new personal cover page template to the <b>server queue directory</b>
before calling this method by using the call sequence of <b>FAX_StartCopyToServer</b>
to retrieve the file name from the server, <b>FAX_WriteFile</b> to write to the
file, and <b>FAX_EndCopy</b> to end the write operation. If this call sequence
was used, the client SHOULD set the <b>bServerBased</b> member of the structure
to FALSE; otherwise the client MUST set the <b>bServerBased</b> member to TRUE.
If <b>bServerBased</b> is FALSE, the server SHOULD validate that the cover page
template specified by the <b>lpwstrCoverPageFileName</b> member has a file
extension of &#34;.cov&#34; and the file name string contains (except for the
terminating null character) only characters representing valid hexadecimal
digits: &#34;0123456789abcdefABCDEF&#34;.</p><p><b>lpcSenderProfile: </b>A pointer to a buffer
containing an array of <b>FAX_PERSONAL_PROFILEW</b> (section <a href="20f6b5ce-e125-4abe-8ac0-0a357376d9da" data-linktype="relative-path">2.2.44</a>) structures that
contain the <b>personal profile</b> (section <a href="bd422bcf-7ce8-4576-addb-89345ea84f9f" data-linktype="relative-path">3.1.1</a>) of the fax sender.
This pointer MUST NOT be <b>NULL</b>.</p><p><b>dwNumRecipients: </b>A <b>DWORD</b> (<a href="../ms-dtyp/cca27429-5689-4a16-b2b4-9325d93e4ba2" data-linktype="relative-path">[MS-DTYP]</a>
section <a href="../ms-dtyp/262627d8-3418-4627-9218-4ffe110850b2" data-linktype="relative-path">2.2.9</a>)
that contains the number of recipients of the fax.</p><p><b>lpcRecipientList: </b>A pointer to an array <b>FAX_PERSONAL_PROFILEW</b>
that contains the <b>personal profiles</b> of the recipients of the fax. The <b>dwNumRecipients</b>
member specifies the number of elements in this array.</p><p><b>lpJobParams: </b>A pointer to a <b>FAX_JOB_PARAM_EXW</b>
(section <a href="5fabf6d9-17dd-4133-b485-8285968d2470" data-linktype="relative-path">2.2.14</a>)
structure that contains the information necessary for the fax server to send
the fax transmission.</p><p><b>lpdwJobId: </b>An optional pointer to a <b>DWORD</b>
to return the job identifier. This parameter is used for backward compatibility
with <b>FaxObs_SendDocument</b> (section <a href="21b87199-d4e7-472c-9190-90c6bb16d947" data-linktype="relative-path">3.1.4.2.7</a>). The fax server
MUST ignore this argument if the fax client submits a <b>NULL</b> pointer value
when making the call.</p><p><b>lpdwlMessageId: </b>A pointer to a <b>DWORDLONG</b>
([MS-DTYP] section <a href="../ms-dtyp/c575fb47-166c-48cd-a37c-e44cac05c3d6" data-linktype="relative-path">2.2.13</a>)
that returns the unique message identifier that represents the fax message to
be sent to all recipients.</p><p><b>lpdwlRecipientMessageIds: </b>A pointer to a <b>DWORDLONG</b>
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 <b>dwNumRecipients</b> member. The elements
in the array SHOULD be ordered in the same order as the elements of the <i>lpcRecipientList</i>
array.</p><p><b>Return Values: </b>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 <a href="cbe6c4fb-4dda-4f6c-9701-0d490ba0d105" data-linktype="relative-path">2.2.52</a>) or one of the
standard errors (<a href="../ms-erref/1bc92ddf-b79e-413c-bbaa-99a5281a6c90" data-linktype="relative-path">[MS-ERREF]</a>
section <a href="../ms-erref/18d8fbe8-a967-4f1c-ae50-99ca8e491d2d" data-linktype="relative-path">2.2</a>).</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Return value/code</p>
   </th>
   <th>
   <p>Description</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>ERROR_ACCESS_DENIED 0x00000005</td>
  <td>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&#39;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&#39;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.</td>
 </tr><tr>
  <td>ERROR_NOT_ENOUGH_MEMORY 0x00000008</td>
  <td>Not enough storage is available to process this command.</td>
 </tr><tr>
  <td>ERROR_INVALID_DATA 0x0000000D</td>
  <td>The file specified by lpcwstrFileName argument is empty (has a size of 0 bytes).</td>
 </tr><tr>
  <td>ERROR_WRITE_PROTECT 0x00000013</td>
  <td>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.</td>
 </tr><tr>
  <td>ERROR_NOT_SUPPORTED 0x00000032</td>
  <td>The fax server SHOULD return this error code when the request described by the lpJobParams argument is not supported by the fax server.&lt;152&gt;</td>
 </tr><tr>
  <td>ERROR_INVALID_PARAMETER 0x00000057</td>
  <td>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,&lt;153&gt;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.</td>
 </tr><tr>
  <td>ERROR_UNSUPPORTED_TYPE 0x0000065E</td>
  <td>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.</td>
 </tr><tr>
  <td>FAX_ERR_NOT_SUPPORTED_ON_THIS_SKU 0x00001B63</td>
  <td>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.&lt;154&gt;</td>
 </tr><tr>
  <td>FAX_ERR_RECIPIENTS_LIMIT 0x00001B65</td>
  <td>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).</td>
 </tr></tbody></table>
</dd></dl><p><b>Exceptions Thrown: </b>No exceptions are thrown
except those that are thrown by the underlying <a href="46aba9c4-ebb1-4b10-86ac-4bb3025657b9#gt_8a7f6700-8311-45bc-af10-82e10accd331" data-linktype="relative-path">RPC</a> protocol <a href="../ms-rpce/290c38b1-92fe-4229-91e6-4fc376610c15" data-linktype="relative-path">[MS-RPCE]</a>.</p></div>