| |
| 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 feature selection and how the connection is
established. |
| POP_OPTION_TRUSTEDSITE |
This option specifies that 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 that 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 that 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_FREETHREAD |
This option specifies that 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 function PopCreateSecurityCredentials can
be used to create this structure if necessary. If a standard
non-secure 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
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
Client: Requires Windows 7, Windows Vista or Windows
XP.
Server: Requires Windows Server 2008 or Windows Server
2003.
Header: Include cstools7.h.
Library: Use cspopav7.lib.
Unicode: Implemented as Unicode and ANSI versions.
See Also
PopAsyncConnect, PopDisconnect, PopInitialize, PopLogin, PopUninitialize
|
|