3.1.4.1.5 FAX_AddOutboundGroup (Opnum 51)

The FAX_AddOutboundGroup (Opnum 51) method is called by the client to add a new outbound routing group.

In response, the server MUST check for the client's fax user account access to write outbound groups. The server MUST check for duplicate group names in a case-insensitive manner. On success, the server MUST add a new outbound routing group to the fax server. Devices can be added to a newly created group by using FAX_SetOutboundGroup (section 3.1.4.1.85).<67>

 error_status_t FAX_AddOutboundGroup(
   [in] handle_t hFaxHandle,
   [in, string, ref] LPCWSTR lpwstrGroupName
 );

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 character string that uniquely identifies a new group name. This value cannot be NULL. The group name is expected to be case-insensitive.

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_ACCESS_MANAGE_CONFIG access rights.

ERROR_DUP_NAME

0x00000034

The group name specified by the lpwstrGroupName parameter is "< All devices>".

ERROR_INVALID_PARAMETER

0x00000057

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_BUFFER_OVERFLOW

0x0000006F

The length of the character string specified by the lpwstrGroupName parameter, excluding the length of the terminating null terminator, is equal to or greater than 128 characters.

ERROR_REGISTRY_CORRUPT

0x000003F7

The fax server cannot store the new outbound routing group configuration in the registry. The registry could be corrupted.

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.<68>

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