3.1.4.2.20 FaxObs_GetRoutingInfo (Opnum 18)

The FaxObs_GetRoutingInfo (Opnum 18) method is called by the client to retrieve information about a routing method.

The client MUST set the FaxPortHandle parameter to a valid fax port handle value returned by the FaxObs_OpenPort (section 3.1.4.2.5) method.

The server MUST validate that the client's fax user account has access to retrieve information about a routing method. The server MUST validate that the RoutingGuid parameter is for a valid routing method. On success, the server MUST return the routing information for a fax routing method that is associated with the specified fax port (device) in the RoutingInfoBuffer parameter.

The client SHOULD free the returned buffer.

 error_status_t FaxObs_GetRoutingInfo(
   [in] RPC_FAX_PORT_HANDLE FaxPortHandle,
   [in, string, unique] LPCWSTR RoutingGuid,
   [in, out, unique, size_is(,*RoutingInfoBufferSize)] 
     LPBYTE* RoutingInfoBuffer,
   [in, out] LPDWORD RoutingInfoBufferSize
 );

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

RoutingGuid: A curly braced GUID string that uniquely identifies the fax routing method for which to obtain the routing information. Fax routing methods are defined by a fax-routing extension and each method is identified by a GUID. For more information about routing methods, see [MSDN-FRM]. The routing methods and their curly braced GUID string values that can be used for this parameter are discoverable by calling FaxObs_EnumRoutingMethods (section 3.1.4.2.18). Included in this list are the default routing methods described in section 2.2.87.

RoutingInfoBuffer: A pointer to the address of the returned buffer containing the fax-routing information. The buffer format and contents depend on the routing method that is identified by RoutingGuid.

RoutingInfoBufferSize: A pointer to a DWORD ([MS-DTYP] section 2.2.9) variable that receives the size, in bytes, of the RoutingInfoBuffer buffer.

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_PORT_QUERY access rights.
ERROR_NOT_ENOUGH_MEMORY 0x00000008	The fax server cannot allocate sufficient memory for the data to be returned to the client.
ERROR_INVALID_DATA 0x0000000D	The data is invalid. This error code is returned when any of the following conditions are met: § The FaxPortHandle argument is not a valid handle obtained using FaxObs_OpenPort.<205> § The GUID specified by the RoutingGuid parameter is not a routing method GUID.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. One or more of the following parameters are set to NULL pointer values: RoutingGuid, RoutingInfoBuffer, RoutingInfoBufferSize.<206>

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