3.1.4.1.65 FAX_OpenPort (Opnum 2)

The FAX_OpenPort (Opnum 2) method is called by the client. In response, the server opens a fax port for subsequent use in other fax methods, and it returns a fax port handle for use by the fax client application.

In response, the server MUST validate whether the client's fax user account has access to open the specified fax port. The server MUST validate that the DeviceId argument that is passed by the client is for a valid device. If the Flags argument specifies PORT_OPEN_MODIFY, the server MUST also confirm that the specified port has not yet been opened for modification, and if the port is already opened for modification, the server MUST fail the request by returning ERROR_INVALID_HANDLE. To indicate success, the server MUST return a new port handle to the client.

 error_status_t FAX_OpenPort(
   [in] handle_t hBinding,
   [in] DWORD DeviceId,
   [in] DWORD Flags,
   [out] PRPC_FAX_PORT_HANDLE FaxPortHandle
 );

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

DeviceId: A DWORD ([MS-DTYP] section 2.2.9) variable that is the line identifier for the device (port). The client SHOULD call the FAX_EnumPorts (section 3.1.4.1.28) method to retrieve a valid value for this parameter.

Flags: A DWORD variable that contains a set of bit flags defining the access mode for the port.<137>

Value/code	Meaning
0x00000000	No port access mode flags are specified.
PORT_OPEN_QUERY 0x00000001	The port access mode that is required to obtain a fax port handle. This access mode is also required to call the FAX_GetPort (section 3.1.4.1.51) method to query fax port information.<138>
PORT_OPEN_MODIFY 0x00000002	The port access mode to change the configuration of a fax port. The fax server can use this port access mode to allow execution of the FAX_SetPort (section 3.1.4.1.88) method. This access mode also includes the allowance that is associated with the PORT_OPEN_QUERY access mode.<139>

FaxPortHandle: A pointer to a variable that receives a fax port handle as described in Fax Data Types (section 2.2.74) which is required on subsequent calls by other fax client methods. This method SHOULD return a NULL handle to indicate an error.

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 either the FAX_ACCESS_QUERY_CONFIG or the FAX_ACCESS_MANAGE_CONFIG access permissions.
ERROR_INVALID_HANDLE 0x00000006	The call was made with the Flags argument containing the PORT_OPEN_MODIFY flag and the port is already opened to be modified by another call.
ERROR_BAD_UNIT 0x00000014	The system cannot find the port for the receiving device by using the line identifier specified by the DeviceId argument.
ERROR_INVALID_PARAMETER 0x00000057	The FaxPortHandle argument is NULL.<140>

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