3.1.4.1.105 FAX_WriteFile (Opnum 70)

The FAX_WriteFile (Opnum 70) method is called by the client.

The server MUST validate the hCopy handle to be a copy handle that has been returned by a previous call to FAX_StartCopyToServer (section 3.1.4.1.97) in the lpHandle output argument. The server MUST validate that the data size is not 0. On success, the server MUST copy the specified data to the file specified by the hCopy copy handle in the server queue directory (section 3.1.1).

The fax client SHOULD split the contents of the file in one or multiple parts (chunks) and individually copy each part (chunk) with a FAX_WriteFile call<180> until the entire file contents are copied. When the entire contents of the file are copied, the fax client MUST notify the fax server by calling the FAX_EndCopy (section 3.1.4.1.15) method as described in Sequencing Rules (section 3.1.4.1.1).

If the fax server fails a FAX_WriteFile call returning ERROR_INVALID_HANDLE during a copy file operation successfully started by the fax client with FAX_StartCopyToServer, the fax client MAY call FAX_StartCopyToServer again to restart the copy file operation from the beginning of the file.

No specific access rights are required for the client's fax user account to successfully call this method.

 error_status_t FAX_WriteFile(
   [in, ref] RPC_FAX_COPY_HANDLE hCopy,
   [in, ref, size_is(dwDataSize)] const LPBYTE lpbData,
   [in, range(0, RPC_COPY_BUFFER_SIZE)] DWORD dwDataSize
 );

hCopy: An RPC context handle that is returned by FAX_StartCopyToServer.

lpbData: A pointer to the buffer from which to copy the file.

dwDataSize: A DWORD ([MS-DTYP] section 2.2.9) value indicating the size, in bytes, of the data buffer pointed by the lpbData argument. This size MUST be between 1 and RPC_COPY_BUFFER_SIZE (16384) bytes.

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.<181>

Return value/code	Description
ERROR_INVALID_HANDLE 0x00000006	The handle value specified by the hCopy argument is not a valid copy handle returned by FAX_StartCopyToServer.
ERROR_GEN_FAILURE 0x0000001F	A device attached to the system is not functioning. The call was unable to write the full amount of the data that was requested to be written.
ERROR_INVALID_PARAMETER 0x00000057	The following conditions can lead to this value being returned: § The parameter is incorrect. § The dwDataSize parameter is 0. § The handle value specified by the hCopy argument is NULL or the buffer size specified by the dwDataSize is zero.

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