FaxOpenPort

The FaxOpenPort function returns a fax port handle to a fax client application. The port handle is required when the application calls other fax client functions that facilitate device management and fax document routing.

BOOL WINAPI FaxOpenPort(
  HANDLE FaxHandle,       // handle to the fax server
  DWORD DeviceId,         // receiving device identifier
  DWORD Flags,            // set of port access level bit flags
  LPHANDLE FaxPortHandle  // fax port handle
);

Parameters

FaxHandle

[in] Specifies a fax server handle returned by a call to the FaxConnectFaxServer function.

DeviceId

[in] Specifies a DWORD variable that is the permanent line identifier for the receiving device. Call the FaxEnumPorts function to retrieve a valid value for this parameter. For more information, see the following Remarks section.

Flags

[in] Specifies a DWORD variable that contains a set of bit flags that defines the access level for the port. This parameter can be one or more of the following values.

Value	Meaning
PORT_OPEN_QUERY	Port access level required to obtain a fax port handle. This access level is also required to call the FaxGetPort function to query fax port information.
PORT_OPEN_MODIFY	Port access level required to change the configuration of a fax port with a call to the FaxSetPort function. This access level also includes the access rights associated with the PORT_OPEN_QUERY access level.

FaxPortHandle

[out] Pointer to a variable that receives a fax port handle that is required on subsequent calls to other fax client functions. If the fax server returns a NULL handle, it indicates an error.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError can return one of the following errors.

Remarks

Call the FaxOpenPort function to obtain the handle to a fax port. Use the handle when you call the following functions:

• FaxSetPort to change the configuration of the port
• FaxEnumRoutingMethods to retrieve information about the fax routing methods associated with a device

The FaxEnumPorts function returns an array of FAX_PORT_INFO structures. Each structure contains detailed information for one port, including a valid value to pass in the DeviceId parameter. An application should not save this device identifier in a persistent manner, because the identifier can change between function calls to the fax server.

For more information, see Fax Ports, Fax Device Management and Managing Fax Routing Data.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable with BackOffice Small Business Server.
  Header: Declared in Winfax.h.
  Library: Included as a resource in Winfax.dll.
  Unicode: Implemented as Unicode and ANSI versions on all platforms.

See Also

Fax Service Client Application Programming Interface Overview, Fax Service Client API Functions, FaxConnectFaxServer, FaxEnumPorts, FaxSetPort, FaxGetPort, FaxInitializeEventQueue, FAX_PORT_INFO