HCLIENT WINAPI PopConnect(
	LPCTSTR lpszRemoteHost,
	UINT nRemotePort,
	UINT nTimeout,
	DWORD dwOptions,
	LPSECURITYCREDENTIALS lpCredentials
);

The PopConnect function is used to establish a connection with the server.

Parameters

lpszRemoteHost

A pointer to the name of the server to connect to; this may be a fully-qualified domain name or an IP address.

nRemotePort

The port number the server is listening on. A value of zero specifies that the default port number should be used. For standard connections, the default port number is 110. For secure connections, the default port number is 995. If the secure port number is specified, an implicit SSL/TLS connection will be established by default.

nTimeout

The number of seconds that the client will wait for a response from the server before failing the current operation.

dwOptions

An unsigned integer that specifies one or more options. This parameter is constructed by using a bitwise operator with any of the following values:

Constant	Description
POP_OPTION_NONE	No connection options specified. A standard connection to the server will be established using the specified host name and port number.
POP_OPTION_LINEBREAK	Message data that is received from the server is read as individual lines of text terminated by a carriage return and linefeed control sequence. This option can be useful for applications that need to use the lower level network I/O functions and must process the message text on a line-by-line basis. This option is not recommended for most applications because it can have a negative impact on performance when retrieving large messages from the server.
POP_OPTION_TUNNEL	This option specifies that a tunneled TCP connection and/or port-forwarding is being used to establish the connection to the server. This changes the behavior of the client with regards to internal checks of the destination IP address and remote port number, default capability selection and how the connection is established.
POP_OPTION_TRUSTEDSITE	This option specifies the server is trusted. The server certificate will not be validated and the connection will always be permitted. This option only affects connections using either the SSL or TLS protocols.
POP_OPTION_SECURE	This option specifies that a secure connection should be established with the server and requires that the server support either the SSL or TLS protocol. This option is the same as specifying POP_OPTION_SECURE_EXPLICIT, which initiates the secure session using the STLS command.
POP_OPTION_SECURE_EXPLICIT	This option specifies the client should attempt to establish a secure connection with the server. The server must support secure connections using either the SSL or TLS protocol and the STLS command.
POP_OPTION_SECURE_IMPLICIT	This option specifies the client should attempt to establish a secure connection with the server. It should only be used when the server expects an implicit SSL connection or does not implement RFC 2595 where the STLS command is used to negotiate a secure connection with the server.
POP_OPTION_SECURE_FALLBACK	This option specifies the client should permit the use of less secure cipher suites for compatibility with legacy servers. If this option is specified, the client will allow connections using TLS 1.0 and cipher suites that use RC4, MD5 and SHA1.
POP_OPTION_PREFER_IPV6	This option specifies the client should prefer the use of IPv6 if the server hostname can be resolved to both an IPv6 and IPv4 address. This option is ignored if the local system does not have IPv6 enabled, or when the hostname can only be resolved to an IPv4 address. If the server hostname can only be resolved to an IPv6 address, the client will attempt to establish a connection using IPv6 regardless if this option has been specified.
POP_OPTION_FREETHREAD	This option specifies the handle returned by this function may be used by any thread, and is not limited to the thread which created it. The application is responsible for ensuring that access to the handle is synchronized across multiple threads.

lpCredentials

A pointer to a SECURITYCREDENTIALS structure which is used to establish the client credentials for a secure connection to the server. The PopCreateSecurityCredentials function can be used to create this structure if necessary. If a standard connection is being established, or client credentials are not required by the server, this parameter can be NULL.

Return Value

If the function succeeds, the return value is a handle to a client session. If the function fails, the return value is INVALID_CLIENT. To get extended error information, call PopGetLastError.

Remarks

To prevent this function from blocking the main user interface thread, the application should create a background worker thread and establish a connection by calling PopConnect in that thread. If the application requires multiple simultaneous connections, it is recommended you create a worker thread for each client session.

The dwOptions argument can be used to specify the threading model that is used by the library when a connection is established. By default, the handle is initially attached to the thread that created it. From that point on, until the it is released, only the owner may call functions using that handle. The ownership of the handle may be transferred from one thread to another using the PopAttachThread function.

Specifying the POP_OPTION_FREETHREAD option enables any thread to call any function using the handle, regardless of which thread created it. It is important to note that this option disables certain internal safety checks which are performed by the library and may result in unexpected behavior unless access to the handle is synchronized. If one thread calls a function in the library, it must ensure that no other thread will call another function at the same time using the same handle.

Requirements

Minimum Desktop Platform: Windows 7 (Service Pack 1)
Minimum Server Platform: Windows Server 2008 R2 (Service Pack 1)
Header File: cstools10.h
Import Library: cspopv10.lib
Unicode: Implemented as Unicode and ANSI versions.

See Also

PopDisconnect, PopInitialize, PopLogin, PopUninitialize

Copyright © 2023 Catalyst Development Corporation. All rights reserved.