3.1.4.1.83 FAX_SetLoggingCategories (Opnum 22)

The FAX_SetLoggingCategories (Opnum 22) method is called by the client. On success, the server MUST modify the current logging categories for the fax server to which the client has connected. A logging category determines the errors or other events that the fax server records in the application event log.

 error_status_t FAX_SetLoggingCategories(
   [in] handle_t hBinding,
   [in, unique, size_is(BufferSize)] 
     const LPBYTE Buffer,
   [in, range(0,FAX_MAX_RPC_BUFFER)] 
     DWORD BufferSize,
   [in] DWORD NumberCategories
 );

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

Buffer: A pointer to an array of the FAX_LOG_CATEGORY (section 2.2.11) structure. Each structure contains the data to modify one logging category. The data includes a friendly name of the logging category, a numeric identifier for the category, and the current severity-level threshold for the category. For more information, see [MSDN-FSCAR].

BufferSize: A variable to return the size, in bytes, of the job information buffer. This variable MUST be set to a value between 1 and 1,048,576. The maximum size is FAX_MAX_RPC_BUFFER (section 2.2.82).

NumberCategories: A DWORD ([MS-DTYP] section 2.2.9) variable that contains the number of FAX_LOG_CATEGORY items that the method passes in 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_MANAGE_CONFIG access rights required for this call.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned under any of the following conditions: § The value specified for the Buffer parameter is NULL. § The value specified for the BufferSize parameter is 0. § The fax server cannot parse the FAX_LOG_CATEGORY pointed at by Buffer, possibly because the buffer data is corrupted. § One of the pointer fields of one of the FAX_LOG_CATEGORY pointed at by Buffer point to memory locations outside of the memory block specified by the Buffer and BufferSize parameters.
ERROR_REGISTRY_CORRUPT 0x000003F7	The registry is corrupted. The fax server cannot write to register the modified logging categories.

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

The FAX_LOG_CATEGORY array MUST be serialized. For more information, see [MSDN-FAX_LOG_CATEGORY]. The variable data fields, such as strings, SHOULD be filled with the offset to the string from the beginning of the buffer and not the actual address.