3.1.4.1.89 FAX_SetPortEx (Opnum 47)

A fax client application uses the FAX_SetPortEx (Opnum 47) method to set fax device information. The function sets extension configuration properties that are stored at the device level, such as enable or disable sending and receiving, and the auto or manual answering of calls. 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, the server MUST validate whether the client's fax user account has access to the server. The server MUST validate that the dwDeviceId that is specified by the client is for a valid device. On success, the server MUST modify the properties of the device as specified by the client.

 error_status_t FAX_SetPortEx(
   [in] handle_t hFaxHandle,
   [in] DWORD dwDeviceId,
   [in, ref] const PFAX_PORT_INFO_EXW pPortInfo
 );

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.

dwDeviceId: A unique identifier that distinguishes the device. The value of dwDeviceId MUST be greater than zero.

pPortInfo: A pointer to a buffer of type FAX_PORT_INFO_EXW (section 2.2.45).

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 caller does not have the required FAX_ACCESS_MANAGE_CONFIG authorization for this operation.
ERROR_BAD_UNIT 0x00000014	The fax server cannot find the device specified by the dwDeviceId parameter.
ERROR_INVALID_PARAMETER 0x00000057	This error code is returned under any of the following conditions: § The value of dwDeviceId is zero. § The size of the structure pointed at by the pPortInfo parameter, or the value of the dwSizeOfStruct field of this structure, do not match the correct size for the FAX_PORT_INFO_EXW. § The ReceiveMode field of the structure pointed at by pPortInfo does not contain a valid value of the FAX_ENUM_DEVICE_RECEIVE_MODE (section 2.2.55) enumeration. § The device specified by dwDeviceId is a virtual device (the Flags field of the FAX_PORT_INFO (section 2.2.7) structure is set to FPF_VIRTUAL) and the ReceiveMode field of the structure pointed at by pPortInfo is FAX_DEVICE_RECEIVE_MODE_MANUAL.
ERROR_BUFFER_OVERFLOW 0x0000006F	The length of the lpwstrDescription character string field of the data structure pointed at by pPortInfo exceeds 253 characters, excluding the length of the NULL string terminator.
ERROR_REGISTRY_CORRUPT 0x000003F7	The fax server cannot store the updated device information to Registry. The Registry might be corrupt.
FAX_ERR_DEVICE_NUM_LIMIT_EXCEEDED 0x00001B62	The fax server cannot complete the operation because the number of active fax devices that are allowed for this version of the operating system was exceeded.<168>

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