3.1.4.1.6 FAX_AddOutboundRule (Opnum 56)

The FAX_AddOutboundRule (Opnum 56) method is called by the client to add a new outbound rule for the specified outbound group to the fax server’s rules map. The value for the dwDeviceId parameter can be obtained using the FAX_EnumPorts (section 3.1.4.1.28) method or the FAX_EnumPortsEx (section 3.1.4.1.29) method.

In response, if bUseGroup is TRUE, the server MUST validate that the group name is valid; if bUseGroup is FALSE, the server MUST validate that the device ID is for a valid device. The server MUST validate that the client's fax user account has access to add an outbound routing rule.

On success, the server MUST add an outbound rule to the fax server.

 error_status_t FAX_AddOutboundRule(
   [in] handle_t hFaxHandle,
   [in] DWORD dwAreaCode,
   [in] DWORD dwCountryCode,
   [in] DWORD dwDeviceId,
   [in, string, unique] LPCWSTR lpwstrGroupName,
   [in] BOOL bUseGroup
 );

hFaxHandle: 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.

dwAreaCode: The area code of the rule. A value of zero indicates the special any-area value ROUTING_RULE_AREA_CODE_ANY. The combination of the dwAreaCode and dwCountryCode parameters is a unique key.

dwCountryCode: The country/region code of the rule. The value of this argument MUST NOT be zero. A value of zero indicates the special any-country, any-region value ROUTING_RULE_COUNTRY_CODE_ANY, which is not valid for this argument. The combination of dwAreaCode and dwCountryCode is a unique key.

dwDeviceId: The destination device of the rule. This value is valid only if the bUseGroup parameter is FALSE. The value of dwDeviceId MUST be greater than zero.

lpwstrGroupName: The destination group of the rule. This value is valid only if bUseGroup is TRUE.

bUseGroup: A Boolean value that specifies whether the group SHOULD be used as the destination.

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 authorization required for this call (FAX_ACCESS_MANAGE_CONFIG).
ERROR_BAD_UNIT 0x00000014	The system cannot find the device specified by the dwDeviceId argument.
ERROR_GEN_FAILURE 0x0000001F	The fax server encountered an exception while processing the character string specified by the lpwstrGroupName argument.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned when any of the following conditions are met: § The country code specified with the dwCountryCode argument is ROUTING_RULE_COUNTRY_CODE_ANY (not a valid rule dialing location). § The lpwstrGroupName argument value is NULL. § The value of the dwDeviceId argument is 0. § The fax server needs to return FAX_ERR_NOT_SUPPORTED_ON_THIS_SKU, but the client fax API version (FAX_API_VERSION_0, described in section 3.1.4.1.10) does not support this error code.
ERROR_BUFFER_OVERFLOW 0x0000006F	The destination group of the rule specified by the lpwstrGroupName argument is longer than the maximum supported value of 128 characters (excluding the terminating null character).
ERROR_REGISTRY_CORRUPT 0x000003F7	The registry is corrupted. The structure of one of the files containing registry data is corrupted, or the system's memory image of the file is corrupted, or the file could not be recovered because the alternate copy or log was absent or corrupted.
FAX_ERR_BAD_GROUP_CONFIGURATION 0x00001B5B	The fax server encountered an outbound routing group with a bad configuration, or the group device list is empty; the status for the new rule object created by the server based on the specified dialing location and device ID is FAX_RULE_STATUS_ALL_GROUP_DEV_NOT_VALID or FAX_RULE_STATUS_EMPTY_GROUP.
FAX_ERR_NOT_SUPPORTED_ON_THIS_SKU 0x00001B63	The fax client module API version (described in section 3.1.4.1.10) is FAX_API_VERSION_1 or above, and the fax server is running on a version of the operating system that does not support the requested operation.<69>

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