3.1.4.2.8 FaxObs_GetQueueFileName (Opnum 6)

The client calls FaxObs_GetQueueFileName (Opnum 6) to obtain from the server the name of a new file located in the fax server queue directory. The client can copy to this file the fax data to be transmitted and submit the file name to FaxObs_SendDocument (section 3.1.4.2.7).

The client SHOULD set the FileNameSize parameter to a value of 255 characters. If the client sets FileNameSize to a value exceeding 255 characters, the server SHOULD NOT write more than 255 characters, including the terminating null character, to the FileName output parameter.

The client's fax user account SHOULD have write file access under the fax server queue directory.<191>

In response, the fax server MUST create a new and unique file within the fax queue directory and return the name of this file, including the server's local directory path to the file. The file name MUST have a ".tif" extension.

The client SHOULD construct the fully qualified UNC path to the file created by the server, by appending the character string returned by this method in FileName to the server's fully qualified domain name (FQDN) followed by "\fax$\queue\", where "fax$" is the name of the share pointing to the local fax queue directory on the server. The server MUST provide the "fax$" share upon the fax server installation.

 error_status_t FaxObs_GetQueueFileName(
   [in] handle_t hBinding,
   [in, out, unique, size_is(FileNameSize)] 
     LPWSTR FileName,
   [in] DWORD FileNameSize
 );

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 buffer that MUST be allocated by the client to hold FileNameSize characters. On successful return from this call the server MUST write to this buffer a null-terminated character string containing the path name, including file name and extension, for a new unique file name within the fax server queue directory.<192>

FileNameSize: A DWORD ([MS-DTYP] section 2.2.9) value that specifies the size, in characters, of the FileName buffer.<193>

Return Values: This method MUST return 0x00000000 (ERROR_SUCCESS) for success; otherwise, it MUST return 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. There are no predefined specific error codes to be returned by this method.

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