3.1.4.1.78 FAX_SetDeviceOrderInGroup (Opnum 55)

The FAX_SetDeviceOrderInGroup (Opnum 55) method is called by the client. 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. The name of the group to remove is specified using the lpwstrGroupName parameter. The value for lpwstrGroupName can be obtained using FAX_EnumOutboundGroups (section 3.1.4.1.26).

The order is the 1-based location of the device in the group. The value of 1 indicates the device is ordered first in the group. The order of devices in the group determines the order in which they are used to send outgoing faxes when the group is selected by an outbound routing rule.

The server MUST validate that the group name length is within allowed. It MUST validate that the client's fax user account has access to manage configuration on the server. It MUST validate that dwNewOrder is within the limits of the specified group.

On success, the server MUST set the order of a single device in the specified group of outbound routing devices.

 error_status_t FAX_SetDeviceOrderInGroup(
   [in] handle_t hFaxHandle,
   [in, string, ref] LPCWSTR lpwstrGroupName,
   [in] DWORD dwDeviceId,
   [in] DWORD dwNewOrder
 );

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.

lpwstrGroupName: A pointer to a null-terminated string that uniquely identifies a group. Group names SHOULD be case-insensitive.

dwDeviceId: A DWORD ([MS-DTYP] section 2.2.9) value specifying the identifier of the device in the group. The specified device MUST exist in the group.

dwNewOrder: A DWORD value specifying the new 1-based order of the device in the group. If there are N devices in the group, this value MUST be between 1 and N (inclusive). Other devices are moved up or down in the group to place the specified device in the specified order.

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 required FAX_ACCESS_MANAGE_CONFIG authorization for this operation.
ERROR_BUFFER_OVERFLOW 0x0000006F	The group name is too long. The length of the character string specified by the lpwstrGroupName parameter, excluding the length of the null terminator, exceeds 128 characters.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned if any of the following conditions are met: § The dwDeviceId or the dwNewOrder parameter is set to a value of 0. § The fax server tried 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_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 device specified by dwDeviceId does not exist in the group identified by the lpwstrGroupName, or the value of dwNewOrder is greater than the number of devices in the group.
FAX_ERR_NOT_SUPPORTED_ON_THIS_SKU 0x00001B63	The fax client module API version (as 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.<160>

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