3.1.4.1.66 FAX_ReadFile (Opnum 71)

The fax client application calls the FAX_ReadFile (Opnum 71) method to copy a file from the server (in chunks).

In response, the server MUST validate that the hCopy context handle refers to a valid copy handle returned by FAX_StartCopyMessageFromServer (section 3.1.4.1.96) and for which FAX_EndCopy (section 3.1.4.1.15) has not been called. To indicate success, the server MUST copy the contents of the message specified by the hCopy handle into the buffer and return the buffer to the client. The server MUST also return the number of bytes it wrote successfully to the buffer. The server MUST NOT write more than dwMaxDataSize bytes to the buffer.

The fax client SHOULD call the FAX_ReadFile (section 3.1.4.1.66) method one or several times, each call reading one part (chunk) of the file.<141> The fax client SHOULD stop calling FAX_ReadFile when the fax server returns a zero number of bytes in the output *lpdwDataSize argument, meaning that no more data is available to be copied from the respective file.

If the fax client calls FAX_ReadFile after the file is entirely copied, the fax server SHOULD return a zero number of bytes in the output *lpdwDataSize argument and write no data in the lpbData buffer.

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

The client MUST allocate the memory for the buffer before making the call and MUST free the buffer when done with the data written by the server in the buffer.

 error_status_t FAX_ReadFile(
   [in, ref] RPC_FAX_COPY_HANDLE hCopy,
   [in] DWORD dwMaxDataSize,
   [out, ref, size_is(*lpdwDataSize)] 
     LPBYTE lpbData,
   [in, out, ref] LPRANGED_DWORD lpdwDataSize
 );

hCopy: A copy handle returned by FAX_StartCopyMessageFromServer.

dwMaxDataSize: A DWORD ([MS-DTYP] section 2.2.9) value that indicates the maximum size, in bytes, of data to be read and returned in the buffer. The caller MUST set this argument to a value greater than zero before making the call.

lpbData: A pointer to the buffer in which to place the data. This data MUST be allocated by the caller to be at least the size specified by the lpdwDataSize argument. The data to be placed in this buffer is a binary data block read from the file indicated by the dwlMessageId and Folder arguments for the FAX_StartCopyMessageFromServer call, which the client used to obtain the hCopy handle.

lpdwDataSize: A pointer to a DWORD in which to return the size, in bytes, of the data that is sent in this segment. The caller MUST set *lpdwDataSize to the same value as dwMaxDataSize before making the call.

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_INVALID_HANDLE 0x00000006	The handle specified by the hCopy argument is not a valid copy handle returned by FAX_StartCopyMessageFromServer for which FAX_EndCopy has not been called.<142>
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned under any of the following conditions: § The handle specified by the hCopy argument is NULL.<143> § The value specified for the dwMaxDataSize argument is zero. § The value specified for the *lpdwDataSize at input (when the call is made) is different than the value specified for the dwMaxDataSize argument.

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