PFAXOPENPORT callback function (winfax.h)

Article
10/13/2021

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.

Syntax

PFAXOPENPORT Pfaxopenport;

BOOL Pfaxopenport(
  [in]  HANDLE FaxHandle,
  [in]  DWORD DeviceId,
  [in]  DWORD Flags,
  [out] LPHANDLE FaxPortHandle
)
{...}

Parameters

[in] FaxHandle

Type: HANDLE

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

[in] DeviceId

Type: DWORD

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.

[in] Flags

Type: DWORD

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.

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 FaxGetPort function. This access level also includes the access rights associated with the PORT_OPEN_QUERY access level.

[out] FaxPortHandle

Type: LPHANDLE

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 value

Type: BOOL

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.

Return code	Description
ERROR_ACCESS_DENIED	Access is denied. FAX_PORT_QUERY access is required.
ERROR_NOT_ENOUGH_MEMORY	An error occurred during memory allocation.
ERROR_INVALID_HANDLE	The port has already been opened with PORT_OPEN_MODIFY access.
ERROR_BAD_UNIT	The DeviceId parameter is invalid.

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

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	winfax.h