FaxConnectFaxServerA function (winfax.h)

The FaxConnectFaxServer function connects a fax client application to the local fax server. The function returns a fax server handle that is required to call other fax client functions that facilitate job, device, configuration, and document management.

Syntax

WINFAXAPI BOOL FaxConnectFaxServerA(
  [in, optional] LPCSTR   MachineName,
  [out]          LPHANDLE FaxHandle
);

Parameters

[in, optional] MachineName

Type: LPCTSTR

This pointer must be NULL (an empty string), so that the application connects to the fax server on the local computer.

[out] FaxHandle

Type: LPHANDLE

Pointer to a variable that receives a fax server 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_INVALID_PARAMETER
The FaxHandle parameter is NULL.
ERROR_NOT_ENOUGH_MEMORY
An error occurred during memory allocation.
ERROR_ACCESS_DENIED
The user under whose account the call was made does not have sufficient rights to the fax server.

Remarks

This function can only be used only with a local server. Use of a remote server is enabled in the Fax Service Extended COM API. For more information see the IFaxServer::Connect method.

A fax client application must call the FaxConnectFaxServer function successfully before it calls any other fax client function.

The fax client application must call the FaxClose function to disconnect from the fax server and deallocate the handle that the FaxConnectFaxServer function returns. For more information, see Connecting to the Fax Server and Disconnecting from a Fax Server.

Note

The winfax.h header defines FaxConnectFaxServer as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

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
Library WinFax.lib

See also

Fax Service Client API Functions

Fax Service Client API for Windows 2000

FaxClose