3.1.4.2.7 FaxObs_SendDocument (Opnum 5)

The client calls the FaxObs_SendDocument (Opnum 5) method to send a document.

In response, the server MUST initiate sending of the specified document to the specified recipient.

To submit a normal (not broadcast) job, the client SHOULD call FaxObs_SendDocument, specifying a valid FileName parameter value and a valid RecipientNumber member of the JobParams structure, setting the first value of the Reserved member of JobParams to zero or to 0xFFFFFFFF on 32-bit or 0x00000000FFFFFFFF on 64-bit. If the first Reserved value is not set to zero, the client SHOULD set the second value of the Reserved member of JobParams to the device identifier describing one fax device (port). The client can obtain the identifier for one fax device (port) by calling the FaxObs_EnumPorts (section 3.1.4.2.15) method or the FaxObs_GetPort (section 3.1.4.2.16) method. If the first Reserved value is zero, the server SHOULD ignore the other two Reserved values and treat this request as a normal job request. <189>

To start a broadcast sequence, the client MUST call FaxObs_SendDocument, specifying a valid FileName parameter value. The client MUST also set the first value of the Reserved member of JobParams to 0xFFFFFFFE on 32-bit or 0x00000000FFFFFFFE on 64-bit, set the second value of the Reserved member of JobParams to 0x00000001 on 32-bit or 0x0000000000000001 on 64-bit, and set the third value of the Reserved member of JobParams to zero. In this case, the server SHOULD ignore all other members of JobParams except the SizeOfStruct and Reserved members, queue the job to be broadcast, and on success return the new job identifier in the FaxJobId output parameter.

To continue and complete a broadcast sequence started as described in the preceding paragraph, the client MUST call again FaxObs_SendDocument once for each intended recipient. For each of these FaxObs_SendDocument calls, the client MUST specify a valid RecipientNumber member of JobParams. The client MUST also set the first value of the Reserved member of JobParams to 0xFFFFFFFE on 32-bit or 0x00000000FFFFFFFE on 64-bit, set the second value of the Reserved member of JobParams to 0x00000002 on 32-bit or 0x0000000000000002 on 64-bit, and set the third value of the Reserved member of JobParams to the job identifier returned by the server to the FaxObs_SendDocument call that started the broadcast sequence. In this case, the server MUST search in the queue for the job identified by the third value of the Reserved member of JobParams and initiate sending of this job to the fax recipient described by JobParams. The server MUST return a new job identifier for each of these FaxObs_SendDocument calls.

When the fax job is successfully queued, the server SHOULD signal to the client a FEI_JOB_QUEUED FAX_EVENT (section 2.2.66) by calling FAX_ClientEventQueue (section 3.2.4.2). If the FEI_JOB_QUEUED event is sent, the job identifier in the FAX_EVENT structure MUST match the job identifier returned by the fax server to the FaxObs_SendDocument call in the FaxJobId output parameter. If the first value of the Reserved field of JobParams is set to 0xFFFFFFFF on 32-bit or 0x00000000FFFFFFFF on 64-bit, the fax server MUST set the DeviceId member of the corresponding FAX_EVENT to the value received in the second value of this Reserved member. If the first value of the Reserved member of JobParams is not set to 0xFFFFFFFF (or 0x00000000FFFFFFFF), the fax server MUST set the DeviceId member of the corresponding FAX_EVENT to 0x00000000.

 error_status_t FaxObs_SendDocument(
   [in] handle_t hBinding,
   [in, string, unique] LPCWSTR FileName,
   [in] const FAX_JOB_PARAMW* JobParams,
   [out] LPDWORD FaxJobId
 );

hBinding: The RPC binding handle for this call. The client SHOULD reuse the RPC binding handle used as an input hBinding argument for the FaxObs_ConnectionRefCount (section 3.1.4.2.2) method call used to connect to the fax server.

FileName: A null-terminated character string that contains the name of the file, without path information, of the fax document in TIFF format. The server checks the server queue directory for this file. Before making this call, the client can create a file on the server by calling FaxObs_GetQueueFileName (section 3.1.4.2.8) and then provide content for the file by using a protocol outside of this specification, such as [MS-SMB].

JobParams: A pointer to a FAX_JOB_PARAMW (section 2.2.13) structure that contains the information necessary for the server to send the fax transmission, including information describing the personal profiles (section 3.1.1) for the sender and the recipient of the fax.

FaxJobId: A pointer to a DWORD ([MS-DTYP] section 2.2.9) that returns the job ID.

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 the FAX_JOB_SUBMIT access rights required for this operation.

ERROR_INVALID_PARAMETER

0x00000057

The parameter is incorrect. This error code is returned under any of the following conditions:

§ The JobParams parameter is set to a NULL pointer value.

§ The FileName parameter is set to a NULL pointer value.

§ The FaxJobId parameter is set to a NULL pointer value.<190>

§ The length of the character string specified by the FileName parameter (excluding the length of the terminating null character) plus the length of the fax queue directory path name (excluding the length of the terminating null character) exceeds 253 characters. This error can occur if the fax client is not using a file path name obtained from FaxObs_GetQueueFileName.

§ Either of the following conditions are true:

§ The first value of the Reserved field of the structure referenced by JobParams is set to 0xFFFFFFFE (32-bit) or 0x00000000FFFFFFFE (64-bit). The second value of this same Reserved field is set to 0x00000002 (32-bit) or 0x0000000000000002 (64-bit). The RecipientNumber field of the same structure is set to NULL.

§ The first value of the Reserved field of the structure referenced by JobParams is not set to 0xFFFFFFFE (32-bit) or 0x00000000FFFFFFFE (64-bit). The CallHandle field of the same structure is not set to 0x00000000. The RecipientNumber field of the JobParams structure is NULL.

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