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 method or the FAX_EnumPortsEx (section 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

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 or FAX_ConnectionRefCount (section 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




Access is denied. The client's fax user account does not have the required FAX_ACCESS_MANAGE_CONFIG authorization for this operation.



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.



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 does not support this error code.



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.



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.



The fax client module API version (as described in section 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].