3.1.4.1.44 FAX_GetLoggingCategories (Opnum 21)

The FAX_GetLoggingCategories (Opnum 21) method is called by the client. In response, the server MUST return 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.

The client SHOULD free the returned buffer.

 error_status_t FAX_GetLoggingCategories(
   [in] handle_t hBinding,
   [out, size_is(, *BufferSize)] LPBYTE* Buffer,
   [out, ref] LPDWORD BufferSize,
   [out, ref] LPDWORD 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 the address of a buffer to receive an array of FAX_LOG_CATEGORY (section 2.2.11) structures. The number of structures included in the array is set by NumberCategories. Each structure describes one current logging category. The Name strings are appended after the FAX_LOG_CATEGORY entries. The Name field of each FAX_LOG_CATEGORY is an offset indicating the location of the associated Name string in the buffer.<113>

BufferSize: A variable to return the size, in bytes, of the buffer.

NumberCategories:  A pointer to a DWORD ([MS-DTYP] section 2.2.9) variable to receive the number of FAX_LOG_CATEGORY that the method returns 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_QUERY_CONFIG access rights required for this operation.
ERROR_NOT_ENOUGH_MEMORY 0x00000008	The server cannot allocate sufficient memory to hold the array of FAX_LOG_CATEGORY to be returned to the client.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned if any of the following conditions are met: § The BufferSize parameter is set to a NULL pointer value.<114> § The NumberCategories parameter is set to a NULL pointer value.<115>
ERROR_ARITHMETIC_OVERFLOW 0x00000216	This error code is returned if any of the following conditions are met: § The total number of logging categories multiplied by the size, in bytes, of the FAX_LOG_CATEGORY Fixed_Size block results in a number that exceeds the maximum value for a DWORD (0xFFFFFFFF). § The total number of logging categories multiplied by the size, in bytes, of the FAX_LOG_CATEGORY Fixed_Size block plus the sum of all lengths, in bytes, including NULL terminators, of all Name strings from the Variable_Data blocks results in a number that exceeds the maximum value for a DWORD (0xFFFFFFFF).
ERROR_INTERNAL_ERROR 0x0000054F	The server failed to custom marshal the array of FAX_LOG_CATEGORY to be returned to the client.

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