3.1.4.1.93 FAX_SetRoutingInfo (Opnum 16)

The FAX_SetRoutingInfo (Opnum 16) method is called by the client to set routing information for a fax routing method.

The server MUST validate that the client's fax user account has access to manage configuration on the server. The server SHOULD validate that the FaxPortHandle is not NULL. The server MUST validate that the RoutingGuid parameter is for a valid routing method. The routing information MUST be passed on to the corresponding routing extension as specified by the RoutingGuid.

On success, the server MUST modify the routing information for the fax routing method that is associated with a specific fax device.

 error_status_t FAX_SetRoutingInfo(
   [in] RPC_FAX_PORT_HANDLE FaxPortHandle,
   [in, string, unique] LPCWSTR RoutingGuid,
   [in, unique, size_is(RoutingInfoBufferSize)] 
     const BYTE* RoutingInfoBuffer,
   [in, range(0,FAX_MAX_RPC_BUFFER)] 
     DWORD RoutingInfoBufferSize
 );

FaxPortHandle: An RPC context handle that references a specified fax port. This context handle MUST be obtained using the FAX_OpenPort (section 3.1.4.1.65) method.

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].For more information about routing methods, see [MSDN-FRM].  The routing methods and the associated curly-braced GUID string values that can be used for this parameter are discoverable by calling FAX_EnumRoutingMethods (section 3.1.4.1.31). Included in this list are the Default Routing Methods described in section 2.2.87.

RoutingInfoBuffer: A pointer to a buffer that contains the new fax routing information. The format and contents of this buffer depend on the routing method identified by the RoutingGuid.

RoutingInfoBufferSize: The size, in bytes, of the RoutingInfoBuffer buffer. The maximum size is the value FAX_MAX_RPC_BUFFER(section 2.2.82).

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	The client's fax user account does not have the FAX_ACCESS_MANAGE_CONFIG permission.
ERROR_INVALID_DATA 0x0000000D	This error code is returned if any of the following conditions are met: § The FaxPortHandle parameter is not set to a valid fax port handle obtained with FAX_OpenPort. § The RoutingGuid parameter is not set to a GUID representing a valid routing method.
ERROR_INVALID_PARAMETER 0x00000057	This error code is returned if any of the following conditions are met: § The RoutingGuid parameter is set to a NULL pointer value. § The RoutingInfoBuffer parameter is set to a NULL pointer value. § The RoutingInfoBufferSize parameter is set to a value of 0. § The FaxPortHandle parameter is set to a NULL value.<172>

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