3.1.4.1.31 FAX_EnumRoutingMethods (Opnum 13)

The FAX_EnumRoutingMethods (Opnum 13) method is called by the client to enumerate all the routing methods for a specified port that are registered with the fax server in the fax server's list of routing methods. The client calls Fax_OpenPort (section 3.1.4.1.65) to get the value for FaxPortHandle. The function returns detailed information about each of the enumerated routing methods.

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

On success, the server MUST fill the buffer with the routing information for the particular port, along with the buffer size and the number of enumerated methods.

The client SHOULD free the buffer.<98>

 error_status_t FAX_EnumRoutingMethods(
   [in] RPC_FAX_PORT_HANDLE FaxPortHandle,
   [out, size_is(, *RoutingInfoBufferSize)] 
     LPBYTE* RoutingInfoBuffer,
   [out, ref] LPDWORD RoutingInfoBufferSize,
   [out, ref] LPDWORD PortsReturned
 );

FaxPortHandle: An RPC context handle that references a specified fax port.

RoutingInfoBuffer: A pointer to the address of a buffer to receive an array of FAX_ROUTING_METHOD (section 2.2.9) structures. Each structure contains information about one fax routing method.

RoutingInfoBufferSize: A variable to return the size, in bytes, of the routing method buffer.

PortsReturned: A pointer to a DWORD ([MS-DTYP] section 2.2.9) variable to receive the number of FAX_ROUTING_METHOD that are returned by the RoutingInfoBuffer 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_INVALID_FUNCTION 0x00000001	The fax server failed to enumerate any routing methods for the fax port specified through the FaxPortHandle parameter.
ERROR_ACCESS_DENIED 0x00000005	Access is denied. The client's fax user account does not have the access rights (FAX_ACCESS_QUERY_CONFIG) required for this operation.
ERROR_NOT_ENOUGH_MEMORY 0x00000008	Not enough storage is available to process this command. The fax server cannot allocate sufficient memory to hold the array of FAX_ROUTING_METHOD to be returned to the client.
ERROR_INVALID_DATA 0x0000000D	This error SHOULD be returned if the FaxPortHandle argument is not a valid handle obtained using FAX_OpenPort.<99>
ERROR_INVALID_PARAMETER 0x00000057	The RoutingInfoBuffer parameter is set to a NULL pointer value. <100>
ERROR_INTERNAL_ERROR 0x0000054F	The fax server failed to custom marshal the array of FAX_ROUTING_METHOD structures to be returned to the client.

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