3.1.4.1.97 FAX_StartCopyToServer (Opnum 68)

The client calls the FAX_StartCopyToServer (Opnum 68) method to start a copy of a file to the server queue directory (section 3.1.1) for which the client's fax user account has access to submit faxes. The server MUST generate a unique file name and create a file with that name in the server queue directory. Then the server MUST create a copy handle and return it to the client to indicate success.

The copy handle returned by the fax server with the lpHandle output argument is valid until the fax client calls FAX_EndCopy (section 3.1.4.1.15), until the fax server is shut down or restarted, or until an implementation-specific condition occurs that invalidates the copy handle on the fax server.

 error_status_t FAX_StartCopyToServer(
   [in] handle_t hFaxHandle,
   [in, string, ref] LPCWSTR lpcwstrFileExt,
   [in, out, string, ref] LPWSTR lpwstrServerFileName,
   [out, ref] PRPC_FAX_COPY_HANDLE lpHandle
 );

hFaxHandle: 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.

lpcwstrFileExt: A null-terminated character string containing the extension of the file to create on the server. The only file name extensions that are supported by the server are ".tif" and ".cov".

lpwstrServerFileName: Pointer to the buffer that receives the null-terminated character string containing the name and specified extension of the file created on the server. The client MUST fill the buffer with any null-terminated character string of sufficient length to accommodate the character string that will be received. The server MUST overwrite this buffer with the null-terminated character string containing the name of the file on the server upon return. The server SHOULD NOT write more than 255 characters, including the terminating null character, to the returned character string.

lpHandle: The copy handle identifying this copy operation.

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 any of the access rights required for this operation: FAX_ACCESS_SUBMIT, FAX_ACCESS_SUBMIT_NORMAL, or FAX_ACCESS_SUBMIT_HIGH.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned under any of the following conditions: § The lpcwstrFileExt parameter is set to a NULL pointer value.<173> § The file extension that is specified by lpcwstrFileExt is not ".cov" or ".tif".
ERROR_BUFFER_OVERFLOW 0x0000006F	The file name is too long. The buffer specified by the lpwstrServerFileName parameter does not have sufficient space to accommodate the server file name.

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