3.1.4.2.5 FaxObs_OpenPort (Opnum 3)

The client calls the FaxObs_OpenPort (Opnum 3) method to open a fax port and obtain a fax port handle.

In response the server opens a fax port for subsequent use in other fax methods and returns a fax port handle for use by the client.

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 parameter that is passed by the client is for a valid device. If the Flags parameter 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 FaxObs_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 FaxObs_ConnectionRefCount (section 3.1.4.2.2) method call used to connect to the fax server.

DeviceId: A DWORD ([MS-DTYP] section 2.2.9) variable that contains the line identifier for the receiving device (port). The client SHOULD call the FaxObs_EnumPorts (section 3.1.4.2.15) 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.<185>

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 level is also required to call the FaxObs_GetPort (section 3.1.4.2.16) method to query fax port information.<186>
PORT_OPEN_MODIFY 0x00000002	The port access mode that allows changes to the configuration of a fax port. The fax server can use this port access mode to allow execution of the FaxObs_SetPort (section 3.1.4.2.17) method. This access mode also includes the allowance that is associated with the PORT_OPEN_QUERY access mode.<187>

FaxPortHandle: A pointer to a variable that receives a fax port handle (from the Fax Data Types (section 2.2.74) enumeration) that is required on subsequent calls by other fax client methods.

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 FAX_PORT_QUERY access rights required for this operation.
ERROR_INVALID_HANDLE 0x00000006	The call was made with the Flags parameter 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 parameter.
ERROR_INVALID_PARAMETER 0x00000057	The FaxPortHandle parameter is set to a NULL pointer value.<188>

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