3.1.4.2.21 FaxObs_SetRoutingInfo (Opnum 19)

The FaxObs_SetRoutingInfo (Opnum 19) method is called by the client to set routing information for a fax 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 configure fax routing methods on the server.

On success, the server MUST modify the routing information for the fax routing method that is associated with the specified fax port (device).

 error_status_t FaxObs_SetRoutingInfo(
   [in] RPC_FAX_PORT_HANDLE FaxPortHandle,
   [in, string, unique] LPCWSTR RoutingGuid,
   [in, unique, size_is(RoutingInfoBufferSize)] 
     const BYTE* RoutingInfoBuffer,
   [in] DWORD 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 to set the routing information for. Fax routing methods are defined by a fax routing extension, and the 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, which 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 a buffer that contains the fax routing information to be set. The format and contents of this buffer depend on the routing method identified by the RoutingGuid parameter.

RoutingInfoBufferSize: 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_SET access rights.
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.<207> § The GUID specified by the RoutingGuid parameter is not a routing method GUID. § The routing extension specified by the RoutingGuid or the routing extension implementing the routing method specified by the RoutingGuid denies the request to set the data requested by the fax client.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. One or more of the following parameters are set to NULL pointer values: RoutingGuid, RoutingInfoBuffer, RoutingInfoBufferSize.

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