3.1.4.1.80 FAX_SetGeneralConfiguration (Opnum 98)

The fax client application calls the FAX_SetGeneralConfiguration (Opnum 98) method to set the configuration options provided for the fax service. The FAX_GENERAL_CONFIG (section 2.2.31) structure MUST be serialized. The variable data fields, such as strings, MUST be filled with the offset to the string from the beginning of the buffer and not the actual address. In response, the server MUST validate that the client's fax user account has access to manage configuration on the server. On success, the server MUST set the requested configuration options.

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

 error_status_t FAX_SetGeneralConfiguration(
   [in] handle_t hBinding,
   [in] DWORD level,
   [in, ref, size_is(BufferSize)] const LPBYTE Buffer,
   [in, range(0,FAX_MAX_RPC_BUFFER)] 
     DWORD 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 to return in Buffer. This value MUST be set to zero.

Buffer: A pointer to a FAX_GENERAL_CONFIG that contains the configuration information to set.

BufferSize: A pointer to a DWORD value that specifies the size, in bytes, of the buffer that is pointed to by the Buffer parameter. The maximum size is FAX_MAX_RPC_BUFFER (section 2.2.82).

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 required FAX_ACCESS_MANAGE_CONFIG authorization for this operation.
ERROR_NOT_ENOUGH_MEMORY 0x00000008	In order to process the data for custom marshaling, the server needs to make a copy of the FAX_GENERAL_CONFIG provided by the client; but the server cannot allocate sufficient memory to hold the copy of the FAX_GENERAL_CONFIG.
ERROR_INVALID_DATA 0x0000000D	The lpcwstrArchiveLocationOffset member of the Fixed_Portion of the FAX_GENERAL_CONFIG referenced by the Buffer parameter is set to an invalid offset value.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned if any of the following conditions are met: § The level parameter is set to a value greater than 0. § In the FAX_GENERAL_CONFIG referenced by Buffer, the dtDiscountStart.Hour member is set to a value greater than or equal to 24, and the dtDiscountStart.Minute member is set to a value greater than or equal to 60. § In the FAX_GENERAL_CONFIG referenced by Buffer, the dtDiscountEnd.Hour member is set to a value greater than or equal to 24, and the dtDiscountEnd.Minute member is set to a value greater than or equal to 60. § In the FAX_GENERAL_CONFIG referenced by Buffer, the bUseArchive member is set to TRUE and the lpcwstrArchiveLocationOffset member is set to 0. § In the FAX_GENERAL_CONFIG referenced by Buffer, the dwSizeQuotaHighWaterMark member is set to a value greater than the value of the dwSizeQuotaLowWaterMark member. § In the FAX_GENERAL_CONFIG referenced by Buffer, the dwQueueState member contains one or more of the following flag values: FAX_INCOMING_BLOCKED, FAX_OUTBOX_BLOCKED, or FAX_OUTBOX_PAUSED. § The value of the BufferSize parameter is less than the size required to hold the custom marshaled FAX_GENERAL_CONFIG structure referenced by Buffer. This size is specified by the dwSizeOfStruct member of the FAX_GENERAL_CONFIG referenced by Buffer.
ERROR_INTERNAL_ERROR 0x0000054F	The server failed to parse the custom marshaled FAX_GENERAL_CONFIG.

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