3.1.4.1.40 FAX_GetGeneralConfiguration (Opnum 97)

The FAX_GetGeneralConfiguration (Opnum 97) method is called by the client to request information about the general configuration at the server.

Protocol version FAX_API_VERSION_0 (0x00000000), FAX_API_VERSION_1 (0x00010000), and FAX_API_VERSION_2 (0x00020000) fax servers SHOULD NOT implement this call. The fax client MUST NOT call this method if the protocol version reported by the server is FAX_API_VERSION_0 (0x00000000), FAX_API_VERSION_1 (0x00010000), or FAX_API_VERSION_2 (0x00020000). For more information, see FAX_ConnectFaxServer (section 3.1.4.1.10).

In response, the server MUST validate that the client's fax user account has access to query configuration. It then MUST allocate memory for the configuration information to be passed out and then fill it with data.

On success, the server MUST return the buffer that contains the configuration information as specified by the level, along with the buffer size.

The client SHOULD free the buffer.

 error_status_t FAX_GetGeneralConfiguration(
   [in] handle_t hBinding,
   [in] DWORD level,
   [out, size_is(,*BufferSize)] LPBYTE* Buffer,
   [out, ref] LPDWORD BufferSize
 );

hBinding: 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 or FAX_ConnectionRefCount (section 3.1.4.1.11) method call used to connect to the fax server.

level: A DWORD ([MS-DTYP] section 2.2.9) value that indicates the type of structure pointed to by Buffer. This MUST be zero.

Buffer: A pointer to a FAX_GENERAL_CONFIG (section 2.2.31) structure that contains the server information to retrieve. The buffer indicated by this pointer contains the following:

§ A serialized FAX_GENERAL_CONFIG filled by server.

§ A null-terminated, wide character string that indicates the archive folder location on the fax server file system.

The lpcwstrArchiveLocation member of the FAX_GENERAL_CONFIG contains the offset to this string in the buffer.

BufferSize: A pointer to a DWORD ([MS-DTYP] section 2.2.9) value that specifies the size, in bytes, of the buffer that is pointed to by the Buffer parameter.

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_ACCESS_QUERY_CONFIG access rights required for this operation.
ERROR_NOT_ENOUGH_MEMORY 0x00000008	Not enough storage is available to process this command. The fax server failed to allocate sufficient memory to hold the FAX_GENERAL_CONFIG to be returned to the client.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. The level parameter is set to a value other than 0.
ERROR_INTERNAL_ERROR 0x0000054F	The fax server failed to custom marshal the FAX_GENERAL_CONFIG to be returned to the client.

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