Socket C Library Reference
Socket
TCP socket C library with SSL capability. Supports both asynchronous connect, accept, send, and read operations in all programming languages. The ActiveX and .NET socket C librarys also include heartbeat, completion, and other events when blocking methods are called. DNS and reverse DNS is support in both synchronous and asynchronous modes. Supports the ability to abort all operations: connect, accept, send, receive, DNS lookups, etc. prior to completion.
Create/Dispose
HCkSocket CkSocket_Create(void);
Creates an instance of the CkSocket object and returns a handle (i.e. a "void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.
void CkSocket_Dispose(HCkSocket handle);
Objects created by calling CkSocket_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.
C "Properties"
BOOL CkSocket_getAsyncAcceptFinished(HCkSocket cHandle);
Set to true when an asynchronous accept operation completes. Once the asynchronous accept has finished, the success/failure is available in the AsyncAcceptSuccess boolean property.
void CkSocket_getAsyncAcceptLog(HCkSocket cHandle, HCkString retval);
Contains the last-error information for an asynchronous accept operation.
BOOL CkSocket_getAsyncAcceptSuccess(HCkSocket cHandle);
Set to true when an asynchronous accept operation completes and is successful.
BOOL CkSocket_getAsyncConnectFinished(HCkSocket cHandle);
Set to true when an asynchronous connect operation completes.
Once the asynchronous connect has finished, the success/failure is available in the AsyncConnectSuccess boolean property.
void CkSocket_getAsyncConnectLog(HCkSocket cHandle, HCkString retval);
Contains the last-error information for an asynchronous connect operation.
BOOL CkSocket_getAsyncConnectSuccess(HCkSocket cHandle);
Set to true when an asynchronous connect operation completes and is successful.
BOOL CkSocket_getAsyncDnsFinished(HCkSocket cHandle);
Set to true when an asynchronous DNS query completes. The success status is available in the AsyncDnsSuccess property.
void CkSocket_getAsyncDnsLog(HCkSocket cHandle, HCkString retval);
Contains the last-error information for an asynchronous DNS query.
void CkSocket_getAsyncDnsResult(HCkSocket cHandle, HCkString retval);
The IP address of the last asynchronous DNS query completed. The IP address is in nnn.nnn.nnn.nnn string form.
BOOL CkSocket_getAsyncDnsSuccess(HCkSocket cHandle);
Set to true when an asynchronous DNS query completes and is successful.
BOOL CkSocket_getAsyncReceiveFinished(HCkSocket cHandle);
Set to true when an asynchronous receive operation completes. Once the asynchronous receive has finished, the success/failure is available in the AsyncReceiveSuccess boolean property.
void CkSocket_getAsyncReceiveLog(HCkSocket cHandle, HCkString retval);
Contains the last-error information for an asynchronous receive operation.
BOOL CkSocket_getAsyncReceiveSuccess(HCkSocket cHandle);
Set to true when an asynchronous receive operation completes and is successful.
void CkSocket_getAsyncReceivedBytes(HCkSocket cHandle, HCkByteData retval);
Contains the data received in an asynchronous receive operation (when receiving bytes asynchronously).
void CkSocket_getAsyncReceivedString(HCkSocket cHandle, HCkString retval);
Contains the string received in an asynchronous receive operation (when receiving a string asynchronously).
BOOL CkSocket_getAsyncSendFinished(HCkSocket cHandle);
Set to true when an asynchronous send operation completes. Once the asynchronous send has finished, the success/failure is available in the AsyncSendSuccess boolean property.
void CkSocket_getAsyncSendLog(HCkSocket cHandle, HCkString retval);
Contains the last-error information for an asynchronous send operation.
BOOL CkSocket_getAsyncSendSuccess(HCkSocket cHandle);
Set to true when an asynchronous send operation completes and is successful.
BOOL CkSocket_getBigEndian(HCkSocket cHandle);
void CkSocket_putBigEndian(HCkSocket cHandle, BOOL newVal);
Applies to the SendCount and ReceiveCount methods. If BigEndian is set to true (the default) then the 4-byte count is in big endian format. Otherwise it is little endian.
void CkSocket_getClientIpAddress(HCkSocket cHandle, HCkString retval);
void CkSocket_putClientIpAddress(HCkSocket cHandle, const char *newVal);
The IP address to use for computers with multiple network interfaces or IP addresses.
For computers with a single network interface (i.e. most computers), this property should not be set. For multihoming computers, the default IP address is automatically used if this property is not set.
The IP address is a string such as in dotted notation using numbers, not domain names, such as "165.164.55.124".
int CkSocket_getClientPort(HCkSocket cHandle);
void CkSocket_putClientPort(HCkSocket cHandle, int newVal);
Normally left at the default value of 0, in which case a unique port is assigned with a value between
1024 and 5000. This property would only be changed if it is specifically required. For example, one
customer's requirements are as follows:
"I have to connect to a Siemens PLC IP server on a technical network.
This machine expects that I connect to its server from a specific IP address using a specific port
otherwise the build in security disconnect the IP connection."
long CkSocket_getConnectFailReason(HCkSocket cHandle);
If the Connect method fails, this property can be checked to determine the reason for failure.
Possible values are:
0 = success
Normal (non-SSL) sockets:
1 = empty hostname
2 = DNS lookup failed
3 = DNS timeout
4 = Aborted by application.
5 = Internal failure.
6 = Connect Timed Out
7 = Connect Rejected (or failed for some other reason)
SSL:
100 = Internal schannel error
101 = Failed to create credentials
102 = Failed to send initial message to proxy.
103 = Handshake failed.
104 = Failed to obtain remote certificate.
long CkSocket_getDebugConnectDelayMs(HCkSocket cHandle);
void CkSocket_putDebugConnectDelayMs(HCkSocket cHandle, long newVal);
Used to simulate a long wait when connecting to a remote server. If your application wishes to test for the handling of timeouts, you may set this value to a number of milliseconds greater than max-wait specified in the Connect method call. The default value is 0.
long CkSocket_getDebugDnsDelayMs(HCkSocket cHandle);
void CkSocket_putDebugDnsDelayMs(HCkSocket cHandle, long newVal);
Used to simulate a long wait when doing a DNS lookup. If your application wishes to test for the handling of timeouts, you may set this value to a number of milliseconds greater than max-wait specified in the DnsLookup method call. The default value is 0.
int CkSocket_getElapsedSeconds(HCkSocket cHandle);
To be documented soon...
long CkSocket_getHeartbeatMs(HCkSocket cHandle);
void CkSocket_putHeartbeatMs(HCkSocket cHandle, long newVal);
The number of milliseconds between periodic heartbeat callbacks for blocking socket operations (connect, accept, dns query, send, receive). Set this to 0 to disable heartbeat events. The default value is 1000 (i.e. 1 heartbeat callback per second).
void CkSocket_getHttpProxyAuthMethod(HCkSocket cHandle, HCkString retval);
void CkSocket_putHttpProxyAuthMethod(HCkSocket cHandle, const char *newVal);
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy authentication method name. Valid choices are "Basic" or "NTLM".
void CkSocket_getHttpProxyHostname(HCkSocket cHandle, HCkString retval);
void CkSocket_putHttpProxyHostname(HCkSocket cHandle, const char *newVal);
If an HTTP proxy is to be used, set this property to the HTTP proxy hostname or IPv4 address (in dotted decimal notation).
void CkSocket_getHttpProxyPassword(HCkSocket cHandle, HCkString retval);
void CkSocket_putHttpProxyPassword(HCkSocket cHandle, const char *newVal);
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy password.
int CkSocket_getHttpProxyPort(HCkSocket cHandle);
void CkSocket_putHttpProxyPort(HCkSocket cHandle, int newVal);
If an HTTP proxy is to be used, set this property to the HTTP proxy port number. (Two commonly used HTTP proxy ports are 8080 and 3128.)
void CkSocket_getHttpProxyUsername(HCkSocket cHandle, HCkString retval);
void CkSocket_putHttpProxyUsername(HCkSocket cHandle, const char *newVal);
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy login name.
BOOL CkSocket_getIsConnected(HCkSocket cHandle);
Returns true if the socket is connected. Otherwise returns false.
Note: This returns the last known state of the socket's connected state. It does not try to send any data on the socket. If a previous call resulted in the socket becoming disconnected, then false will be returned. However, if the socket was connected and the peer disconnects prior to any Chilkat Socket method calls that would send/received data (and discover the disconnection), then this will return true. In a nutshell, if this returns false, then it is known for sure that the socket is not connected, if it returns true then the last-known state of the socket was connected.
BOOL CkSocket_getKeepSessionLog(HCkSocket cHandle);
void CkSocket_putKeepSessionLog(HCkSocket cHandle, BOOL newVal);
Controls whether socket (or SSL) communications are logged to the SessionLog string property. To turn on session logging, set this property = true, otherwise set to false (which is the default value).
void CkSocket_getLastErrorHtml(HCkSocket cHandle, HCkString retval);
Error information in HTML format for the last method called.
void CkSocket_getLastErrorText(HCkSocket cHandle, HCkString retval);
Error information in plain-text format for the last method called.
void CkSocket_getLastErrorXml(HCkSocket cHandle, HCkString retval);
Error information in XML format for the last method called.
BOOL CkSocket_getLastMethodFailed(HCkSocket cHandle);
true if the last method called on this object failed. This provides an easier (less confusing) way of determining whether a method such as ReceiveBytes succeeded or failed.
void CkSocket_getLocalIpAddress(HCkSocket cHandle, HCkString retval);
The local IP address for a bound or connected socket.
int CkSocket_getLocalPort(HCkSocket cHandle);
The local port for a bound or connected socket.
long CkSocket_getMaxReadIdleMs(HCkSocket cHandle);
void CkSocket_putMaxReadIdleMs(HCkSocket cHandle, long newVal);
The maximum number of milliseconds to wait on a socket read operation while no additional data is forthcoming. To wait indefinitely, set this property to 0. The default value is 0.
long CkSocket_getMaxSendIdleMs(HCkSocket cHandle);
void CkSocket_putMaxSendIdleMs(HCkSocket cHandle, long newVal);
The maximum number of milliseconds to wait for the socket to become writeable on a socket write operation. To wait indefinitely, set this property to 0. The default value is 0.
void CkSocket_getMyIpAddress(HCkSocket cHandle, HCkString retval);
The local IP address of the local computer. For multi-homed computers (i.e. computers with multiple IP adapters) this property returns the default IP address.
Note: This will be the internal IP address, not an external IP address. (For example, if your computer is on a LAN, it is likely to be an IP address beginning with "192.168.".
Important: Use LocalIpAddress and LocalIpPort to get the local IP/port for a bound or connected socket.
int CkSocket_getNumSocketsInSet(HCkSocket cHandle);
If this socket is a "socket set", then NumSocketsInSet returns the number of sockets contained in the set. A socket object can become a "socket set" by calling the TakeSocket method on one or more connected sockets. This makes it possible to select for reading on the set (i.e. wait for data to arrive from any one of multiple sockets). See the following methods and properties for more information: TakeSocket, SelectorIndex, SelectorReadIndex, SelectorWriteIndex, SelectForReading, SelectForWriting.
long CkSocket_getObjectId(HCkSocket cHandle);
Each socket object is assigned a unique object ID. This ID is passed in event callbacks to allow your application to associate the event with the socket object.
long CkSocket_getReceivePacketSize(HCkSocket cHandle);
void CkSocket_putReceivePacketSize(HCkSocket cHandle, long newVal);
The number of bytes to receive at a time (internally). This setting has an effect on methods such as ReadBytes and ReadString where the number of bytes to read is not explicitly specified. The default value is 4096.
void CkSocket_getRemoteIpAddress(HCkSocket cHandle, HCkString retval);
When a socket is connected, the remote IP address of the connected peer is available in this property.
long CkSocket_getRemotePort(HCkSocket cHandle);
When a socket is connected, the remote port of the connected peer is available in this property.
int CkSocket_getSelectorIndex(HCkSocket cHandle);
void CkSocket_putSelectorIndex(HCkSocket cHandle, int newVal);
If this socket contains a collection of connected sockets (i.e. it is a "socket set") then method calls and property gets/sets are routed to the contained socket indicated by this property. Indexing begins at 0. See the TakeSocket method and SelectForReading method for more information.
int CkSocket_getSelectorReadIndex(HCkSocket cHandle);
void CkSocket_putSelectorReadIndex(HCkSocket cHandle, int newVal);
When SelectForReading returns a number greater than 0 indicating that 1 or more sockets are ready for reading, this property is used to select the socket in the "ready set" for reading. See the example below:
int CkSocket_getSelectorWriteIndex(HCkSocket cHandle);
void CkSocket_putSelectorWriteIndex(HCkSocket cHandle, int newVal);
To be documented soon.
long CkSocket_getSendPacketSize(HCkSocket cHandle);
void CkSocket_putSendPacketSize(HCkSocket cHandle, long newVal);
The number of bytes to send at a time (internally). This can also be though of as the "chunk size". If a large amount of data is to be sent, the data is sent in chunks equal to this size in bytes. The default value is 65535. (Note: This only applies to non-SSL/TLS connections. SSL and TLS have their own pre-defined packet sizes.)
void CkSocket_getSessionLog(HCkSocket cHandle, HCkString retval);
Contains a log of the bytes sent and received on this socket. The KeepSessionLog property must be set to true for logging to occur.
void CkSocket_getSessionLogEncoding(HCkSocket cHandle, HCkString retval);
void CkSocket_putSessionLogEncoding(HCkSocket cHandle, const char *newVal);
Controls how the data is encoded in the SessionLog. Possible values are "esc" and "hex". The default value is "esc".
When set to "hex", the bytes are encoded as a hexidecimalized string.
The "esc" encoding is a C-string like encoding, and is more compact than hex if most of the data to be logged is text. Printable us-ascii chars are unmodified. Common "C" control chars are represented as "\r", "\n", "\t", etc. Non-printable and byte values greater than 0x80 are escaped using a backslash and hex encoding: \xHH. Certain printable chars are backslashed: SPACE, double-quote, single-quote, etc.
int CkSocket_getSoRcvBuf(HCkSocket cHandle);
void CkSocket_putSoRcvBuf(HCkSocket cHandle, int newVal);
Sets the SO_RCVBUF socket option. In most cases this should be left unset.
int CkSocket_getSoSndBuf(HCkSocket cHandle);
void CkSocket_putSoSndBuf(HCkSocket cHandle, int newVal);
Sets the SO_SNDBUF socket option. In most cases this should be left unset.
void CkSocket_getSocksHostname(HCkSocket cHandle, HCkString retval);
void CkSocket_putSocksHostname(HCkSocket cHandle, const char *newVal);
The SOCKS4/SOCKS5 hostname or IPv4 address (in dotted decimal notation). This property is only used if the SocksVersion property is set to 4 or 5).
void CkSocket_getSocksPassword(HCkSocket cHandle, HCkString retval);
void CkSocket_putSocksPassword(HCkSocket cHandle, const char *newVal);
The SOCKS5 password (if required). The SOCKS4 protocol does not include the use of a password, so this does not apply to SOCKS4.
int CkSocket_getSocksPort(HCkSocket cHandle);
void CkSocket_putSocksPort(HCkSocket cHandle, int newVal);
The SOCKS4/SOCKS5 proxy port. The default value is 1080.
This property only applies if a SOCKS proxy is used (if the SocksVersion property is set to 4 or 5).
void CkSocket_getSocksUsername(HCkSocket cHandle, HCkString retval);
void CkSocket_putSocksUsername(HCkSocket cHandle, const char *newVal);
The SOCKS4/SOCKS5 proxy username. This property is only used if the SocksVersion property is set to 4 or 5).
int CkSocket_getSocksVersion(HCkSocket cHandle);
void CkSocket_putSocksVersion(HCkSocket cHandle, int newVal);
SocksVersion
May be set to one of the following integer values:
0 - No SOCKS proxy is used. This is the default.
4 - Connect via a SOCKS4 proxy.
5 - Connect via a SOCKS5 proxy.
BOOL CkSocket_getSsl(HCkSocket cHandle);
void CkSocket_putSsl(HCkSocket cHandle, BOOL newVal);
Set this property to true if the socket requires an SSL connection. The default value is false.
void CkSocket_getSslProtocol(HCkSocket cHandle, HCkString retval);
void CkSocket_putSslProtocol(HCkSocket cHandle, const char *newVal);
Selects the secure protocol to be used for secure (SSL) connections. Possible values are:
default
TLS 1.0
SSL 3.0
SSL 2.0
PCT 1.0
The default value is "default", which allows for the protocol to be selected dynamically at runtime based on the requirements of the server.
void CkSocket_getStringCharset(HCkSocket cHandle, HCkString retval);
void CkSocket_putStringCharset(HCkSocket cHandle, const char *newVal);
A charset such as "utf-8", "windows-1252", "Shift_JIS", "iso-8859-1", etc. Methods for sending and receiving strings will use this charset as the encoding. Strings sent on the socket are first converted (if necessary) to this encoding. When reading, it is assumed that the bytes received are converted FROM this charset if necessary. This ONLY APPLIES TO THE SendString and ReceiveString methods. The default value is "ansi".
BOOL CkSocket_getTcpNoDelay(HCkSocket cHandle);
void CkSocket_putTcpNoDelay(HCkSocket cHandle, BOOL newVal);
Controls whether the TCP_NODELAY socket option is used for the underlying TCP/IP socket. The default value is false. Setting the value to true disables the Nagle algorithm and allows for better performance when small amounts of data are sent on the socket connection.
void CkSocket_getUserData(HCkSocket cHandle, HCkString retval);
void CkSocket_putUserData(HCkSocket cHandle, const char *newVal);
To be documented soon...
BOOL CkSocket_getUtf8(HCkSocket cHandle);
void CkSocket_putUtf8(HCkSocket cHandle, BOOL newVal);
When set to true, all "const char *" arguments are expected to be utf-8 strings. If set to false, the "const char *" arguments are expected to be ANSI strings.
BOOL CkSocket_getVerboseLogging(HCkSocket cHandle);
void CkSocket_putVerboseLogging(HCkSocket cHandle, BOOL newVal);
If set to true, causes LastErrorText to be more verbose. The default is false.
void CkSocket_getVersion(HCkSocket cHandle, HCkString retval);
The version of this component, such as "v1.0.0"
C "Methods"
HCkSocket CkSocket_AcceptNextConnection(HCkSocket cHandle, int maxWaitMs);
Blocking call to accept the next incoming connection on the socket. maxWaitMs specifies the maximum time to wait (in milliseconds). Set this to 0 to wait indefinitely. If successful, a new socket object is returned.
Important: If accepting an SSL/TLS connection, the SSL handshake is part of the connection establishment process. This involves a few back-and-forth messages between the client and server to establish algorithms and a shared key to create the secure channel. The sending and receiving of these messages are governed by the MaxReadIdleMs and MaxSendIdleMs properties. If these properties are set to 0 (and this is the default unless changed by your application), then the AcceptNextConnection can hang indefinitely during the SSL handshake process. Make sure these properties are set to appropriate values before calling this method.
void CkSocket_AsyncAcceptAbort(HCkSocket cHandle);
Call this to abort an asynchronous socket connect that is running in a background thread. Asynchronous connects are initiated by calling AsyncAcceptStart.
HCkSocket CkSocket_AsyncAcceptSocket(HCkSocket cHandle);
Returns the socket object for the connection accepted asynchronously in a background thread (via AsyncAcceptStart). The connected socket can only be retrieved once. A subsequent call to AsyncAcceptSocket will return a NULL reference until another connection is accepted asynchronously.
BOOL CkSocket_AsyncAcceptStart(HCkSocket cHandle, int maxWaitMs);
Initiates a background thread to wait for and accept the next incoming TCP connection. The method will fail if an asynchronous operation is already in progress, or if the timeout expired. The timeout (in milliseconds) is passed in maxWaitMs. To wait indefinitely, set maxWaitMs to 0. Asynchronous accept operations can be aborted by calling AsyncAcceptAbort. When the async accept operation completes, the AsyncAcceptFinished property will become true. If the accept was successful, the AsyncAcceptSuccess property is set to true and the connected socket can be retrieved via the AsyncAcceptSocket method. A debug log is available in the AsyncAcceptLog property. Returns TRUE for success, FALSE for failure.
void CkSocket_AsyncConnectAbort(HCkSocket cHandle);
Aborts an asynchronous connect operation running in a background thread (started by calling AsyncConnectStart).
BOOL CkSocket_AsyncConnectStart(HCkSocket cHandle, const char *hostname, int port, BOOL ssl, int maxWaitMs);
Initiates a background thread to establish a TCP connection with a remote host:port. The method will fail if an asynchronous operation is already in progress, or if the timeout expired. The timeout (in milliseconds) is passed in maxWaitMs. To wait indefinitely, set maxWaitMs to 0. Set ssl = true to esablish an SSL connection. Asynchronous connect operations can be aborted by calling AsyncConnectAbort. When the async connect operation completes, the AsyncConnectFinished property will become true. If the connect was successful, the AsyncConnectSuccess property is set to true. A debug log is available in the AsyncConnectLog property. Returns TRUE for success, FALSE for failure.
void CkSocket_AsyncDnsAbort(HCkSocket cHandle);
Aborts an asynchronous DNS lookup running in a background thread (started via the AsyncDnsStart method).
BOOL CkSocket_AsyncDnsStart(HCkSocket cHandle, const char *hostname, int maxWaitMs);
Initiates a background thread to do a DNS query (i.e. to resolve a hostname to an IP address). The method will fail if an asynchronous operation is already in progress, or if the timeout expired. The timeout (in milliseconds) is passed in maxWaitMs. To wait indefinitely, set maxWaitMs to 0. Asynchronous DNS lookups can be aborted by calling AsyncDnsAbort. When the async DNS operation completes, the AsyncDnsFinished property will become true. If the DNS query was successful, the AsyncDnsSuccess property is set to true. A debug log is available in the AsyncDnsLog property. Finally, the DNS query result (i.e. IP address) is available in nnn.nnn.nnn.nnn string form in the AsyncDnsResult property. Returns TRUE for success, FALSE for failure.
void CkSocket_AsyncReceiveAbort(HCkSocket cHandle);
Aborts an asynchronous receive running in a background thread (started via one of the AsyncReceive* methods).
BOOL CkSocket_AsyncReceiveBytes(HCkSocket cHandle);
Initiates a background thread to receive bytes on an already-connected socket (ssl or non-ssl). Returns TRUE for success, FALSE for failure.
BOOL CkSocket_AsyncReceiveBytesN(HCkSocket cHandle, unsigned long numBytes);
Initiates a background thread to receive exactly numBytes bytes on an already-connected socket (ssl or non-ssl). Returns TRUE for success, FALSE for failure.
BOOL CkSocket_AsyncReceiveString(HCkSocket cHandle);
Initiates a background thread to receive text on an already-connected socket (ssl or non-ssl). The component interprets the received bytes according to the charset specified in the StringCharset property. Returns TRUE for success, FALSE for failure.
BOOL CkSocket_AsyncReceiveToCRLF(HCkSocket cHandle);
Initiates a background thread to receive text on an already-connected socket (ssl or non-ssl). The asynchronous receive does not complete until a CRLF is received. The component interprets the received bytes according to the charset specified in the StringCharset property. Returns TRUE for success, FALSE for failure.
BOOL CkSocket_AsyncReceiveUntilMatch(HCkSocket cHandle, const char *matchStr);
Initiates a background thread to receive text on an already-connected socket (ssl or non-ssl). The asynchronous receive does not complete until the exact string specified by matchStr is received. The component interprets the received bytes according to the charset specified in the StringCharset property. Returns TRUE for success, FALSE for failure.
void CkSocket_AsyncSendAbort(HCkSocket cHandle);
Aborts an asynchronous send running in a background thread (started via one of the AsyncSend* methods).
BOOL CkSocket_AsyncSendBytes(HCkSocket cHandle, const unsigned char *byteData, unsigned long numBytes);
Initiates a background thread to send bytes on an already-connected socket (ssl or non-ssl). Returns TRUE for success, FALSE for failure.
BOOL CkSocket_AsyncSendString(HCkSocket cHandle, const char *str);
Initiates a background thread to send text on an already-connected socket (ssl or non-ssl). Before sending, the stringToSend is first converted (if necessary) to the charset specified by the StringCharset property. Returns TRUE for success, FALSE for failure.
BOOL CkSocket_BindAndListen(HCkSocket cHandle, int port, int backlog);
Binds a TCP socket to a port and configures it to listen for incoming connections. The size of the backlog is passed in backLog. The backlog is necessary when multiple connections arrive at the same time, or close enough in time such that they cannot be serviced immediately. (A typical value to use for backLog is 5.) This method should be called once prior to receiving incoming connection requests via the AcceptNextConnection or AsyncAcceptStart methods. Returns TRUE for success, FALSE for failure.
void CkSocket_BuildHttpGetRequest(HCkSocket cHandle, const char *url, HCkString str);
Convenience method for converting a full URL with query parameters into an HTTP GET request. The full HTTP GET request is returned as a string.
int CkSocket_CheckWriteable(HCkSocket cHandle, int maxWaitMs);
Determines if the socket is writeable. Returns one of the following integer values:
1: If the socket is connected and ready for writing.
0: If a timeout occurred or if the application aborted the method during an event callback.
-1: The socket is not connected.
void CkSocket_ClearSessionLog(HCkSocket cHandle);
Clears the contents of the SessionLog property.
void CkSocket_Close(HCkSocket cHandle, int maxWaitMs);
Cleanly terminates and closes a TCP/IP (SSL or non-SSL) connection. The maxWaitMs applies to SSL connections because there is a handshake that occurs during secure channel shutdown.
BOOL CkSocket_Connect(HCkSocket cHandle, const char *hostname, int port, BOOL ssl, int maxWaitMs);
Establishes an SSL or non-SSL connection with a remote host:port. This is a blocking call. To initiate a non-blocking (asynchronous) connection in a background thread, call AsyncConnectStart. The maximum wait time (in milliseconds) is passed in maxWaitMs. To establish an SSL connection, set ssl = true, otherwise set ssl = false.
Note: Connections do not automatically close because of inactivity. A connection will remain open indefinitely even if there is no activity. Returns TRUE for success, FALSE for failure. SSL/TLS Error -- SEC_E_INTERNAL_ERROR
BOOL CkSocket_ConvertFromSsl(HCkSocket cHandle);
Closes the secure (TLS/SSL) channel leaving the socket in a connected state where data sent and received is unencrypted. Returns TRUE for success, FALSE for failure.
BOOL CkSocket_ConvertToSsl(HCkSocket cHandle);
Converts a non-SSL/TLS connected socket to a secure channel using TLS/SSL. Returns TRUE for success, FALSE for failure.
BOOL CkSocket_DnsLookup(HCkSocket cHandle, const char *hostname, int maxWaitMs, HCkString outStr);
Performs a DNS query to resolve a hostname to an IP address. The IP address is returned if successful. The maximum time to wait (in milliseconds) is passed in maxWaitMs. To wait indefinitely, set maxWaitMs = 0.
HCkCert CkSocket_GetMyCert(HCkSocket cHandle);
Returns the digital certificate to be used for SSL connections. This method would only be called by an SSL server application. The SSL certificate is initially specified by calling InitSslServer.
HCkCert CkSocket_GetSslServerCert(HCkSocket cHandle);
Returns the SSL server's digital certificate. This method would only be called by the client-side of an SSL connection. It returns the certificate of the remote SSL server for the current SSL connection. If the socket is not connected, or is not connected via SSL, then a NULL reference is returned.
BOOL CkSocket_InitSslServer(HCkSocket cHandle, HCkCert cert);
SSL Server applications should call this method with the SSL server certificate to be used for SSL connections. Returns TRUE for success, FALSE for failure.
BOOL CkSocket_IsUnlocked(HCkSocket cHandle);
Returns true if the component is unlocked.
BOOL CkSocket_PollDataAvailable(HCkSocket cHandle);
Check to see if data is available for reading on the socket. Returns true if data is waiting and false if no data is waiting to be read.
BOOL CkSocket_ReceiveBytes(HCkSocket cHandle, HCkByteData byteData);
Receives as much data as is immediately available on a connected TCP socket. If no data is immediately available, it waits up to MaxReadIdleMs milliseconds for data to arrive.
BOOL CkSocket_ReceiveBytesN(HCkSocket cHandle, unsigned long numBytes, HCkByteData byteData);
Reads exactly numBytes bytes from a connected SSL or non-SSL socket. This method blocks until numBytes bytes are read or the read times out. The timeout is specified by the MaxReadIdleMs property (in milliseconds).
BOOL CkSocket_ReceiveBytesToFile(HCkSocket cHandle, const char *appendFilename);
Receives as much data as is immediately available on a connected TCP socket. If no data is immediately available, it waits up to MaxReadIdleMs milliseconds for data to arrive.
The received data is appended to the file specified by appendFilename. Returns TRUE for success, FALSE for failure.
int CkSocket_ReceiveCount(HCkSocket cHandle);
Receives a 4-byte signed integer and returns the value received. Returns -1 on error.
BOOL CkSocket_ReceiveString(HCkSocket cHandle, HCkString strOut);
Receives as much data as is immediately available on a TCP/IP or SSL socket. If no data is immediately available, it waits up to MaxReadIdleMs milliseconds for data to arrive. The incoming bytes are interpreted according to the StringCharset property and returned as a string.
BOOL CkSocket_ReceiveStringMaxN(HCkSocket cHandle, int maxBytes, HCkString outStr);
Same as ReceiveString, but limits the amount of data returned to a maximum of maxByteCount bytes.
(Receives as much data as is immediately available on the TCP/IP or SSL socket. If no data is immediately available, it waits up to MaxReadIdleMs milliseconds for data to arrive. The incoming bytes are interpreted according to the StringCharset property and returned as a string.)
BOOL CkSocket_ReceiveStringUntilByte(HCkSocket cHandle, int byteValue, HCkString outStr);
Receives bytes on a connected SSL or non-SSL socket until a specific 1-byte value is read. Returns a string containing all the bytes up to but excluding the lookForByte.
BOOL CkSocket_ReceiveToCRLF(HCkSocket cHandle, HCkString outStr);
Reads text from the connected TCP/IP or SSL socket until a CRLF is received. Returns the text up to and including the CRLF. The incoming bytes are interpreted according to the charset specified by the StringCharset property.
BOOL CkSocket_ReceiveUntilByte(HCkSocket cHandle, int byteValue, HCkByteData outBytes);
Receives bytes on the TCP/IP or SSL socket until a specific 1-byte value is read. Returns all the bytes up to and including the lookForByte.
BOOL CkSocket_ReceiveUntilMatch(HCkSocket cHandle, const char *matchStr, HCkString strOut);
Reads text from the connected TCP/IP or SSL socket until a matching string (matchStr) is received. Returns the text up to and including the matching string. As an example, to one might read the header of an HTTP request or a MIME message by reading up to the first double CRLF ("\r\n\r\n"). The incoming bytes are interpreted according to the charset specified by the StringCharset property.
BOOL CkSocket_SaveLastError(HCkSocket cHandle, const char *filename);
Saves the last error information to an XML formatted file.
int CkSocket_SelectForReading(HCkSocket cHandle, int timeoutMs);
Wait for data to arrive on this socket, or any of the contained sockets if the caller is a "socket set".
(see the example at the link below for more detailed information)
Waits a maximum
of timeoutMs milliseconds. If maxWaitMs = 0, then it is effectively a poll.
Returns the number of sockets with data available for reading.
If no sockets have data available for reading, then a value of 0 is
returned. A value of -1 indicates an error condition.
Note: when the remote peer (in this case the web server) disconnects,
the socket will appear as if it has data available. A "ready" socket
is one where either data is available for reading or the socket has
become disconnected.
If the peer closed the connection, it will not be discovered until an attempt is made to read the socket. If the read fails, then the IsConnected property may be checked to see if the connection was closed.
int CkSocket_SelectForWriting(HCkSocket cHandle, int timeoutMs);
To be documented soon.
BOOL CkSocket_SendBytes(HCkSocket cHandle, const unsigned char *byteData, unsigned long numBytes);
Sends bytes over a connected SSL or non-SSL socket. If transmission halts for more than MaxSendIdleMs milliseconds, the send is aborted. This is a blocking (synchronous) method. It returns only after the bytes have been sent. Returns TRUE for success, FALSE for failure.
BOOL CkSocket_SendCount(HCkSocket cHandle, int byteCount);
Sends a 4-byte signed integer on the connection. The receiver may call ReceiveCount to receive the integer. The SendCount and ReceiveCount methods are handy for sending byte counts prior to sending data. The sender would send a count followed by the data, and the receiver would receive the count first, and then knows how many data bytes it should expect to receive. Returns TRUE for success, FALSE for failure.
BOOL CkSocket_SendString(HCkSocket cHandle, const char *str);
Sends a string over a connected SSL or non-SSL (TCP/IP) socket. If transmission halts for more than MaxSendIdleMs milliseconds, the send is aborted. The string is sent in the charset encoding specified by the StringCharset property.
This is a blocking (synchronous) method. It returns after the string has been sent. Returns TRUE for success, FALSE for failure.
void CkSocket_SetSslClientCert(HCkSocket cHandle, HCkCert cert);
A client-side certificate for SSL/TLS connections is optional. It should be used only if the server demands it. This method allows the certificate to be specified using a certificate object.
BOOL CkSocket_SetSslClientCertPfx(HCkSocket cHandle, const char *pfxFilename, const char *pfxPassword, const char *certSubjectCN);
A client-side certificate for SSL/TLS connections is optional. It should be used only if the server demands it. This method allows the certificate to be specified using a PFX file.
void CkSocket_SleepMs(HCkSocket cHandle, int millisec);
Convenience method to force the calling process to sleep for a number of milliseconds.
void CkSocket_StartTiming(HCkSocket cHandle);
To be documented soon...
BOOL CkSocket_TakeSocket(HCkSocket cHandle, HCkSocket sock);
Takes ownership of the sock. sock is added to the internal set of connected sockets.
The object is now effectively a "socket set", i.e. a collection of connected sockets.
Method calls are routed to the internal sockets based on the value of the SelectorIndex property.
For example, if SelectorIndex equals 2, then a call to SendBytes is actually a call to SendBytes
on the 3rd socket in the set. (Indexing begins at 0.) Likewise, getting and setting properties
are also routed to the contained socket based on SelectorIndex. It is possible to wait on a
set of sockets for data to arrive on any of them by calling SelectForReading. See the example below: Returns TRUE for success, FALSE for failure.
BOOL CkSocket_UnlockComponent(HCkSocket cHandle, const char *code);
Unlocks the component allowing for the full functionality to be used. An arbitrary string can be passed to initiate a fully-functional 30-day trial. Returns TRUE for success, FALSE for failure.
const char *CkSocket_asyncAcceptLog(HCkSocket cHandle);
Contains the last-error information for an asynchronous accept operation.
const char *CkSocket_asyncConnectLog(HCkSocket cHandle);
Contains the last-error information for an asynchronous connect operation.
const char *CkSocket_asyncDnsLog(HCkSocket cHandle);
Contains the last-error information for an asynchronous DNS query.
const char *CkSocket_asyncDnsResult(HCkSocket cHandle);
The IP address of the last asynchronous DNS query completed. The IP address is in nnn.nnn.nnn.nnn string form.
const char *CkSocket_asyncReceiveLog(HCkSocket cHandle);
Contains the last-error information for an asynchronous receive operation.
const char *CkSocket_asyncReceivedString(HCkSocket cHandle);
Contains the string received in an asynchronous receive operation (when receiving a string asynchronously).
const char *CkSocket_asyncSendLog(HCkSocket cHandle);
Contains the last-error information for an asynchronous send operation.
const char *CkSocket_buildHttpGetRequest(HCkSocket cHandle, const char *url);
Convenience method for converting a full URL with query parameters into an HTTP GET request. The full HTTP GET request is returned as a string.
const char *CkSocket_clientIpAddress(HCkSocket cHandle);
The IP address to use for computers with multiple network interfaces or IP addresses.
For computers with a single network interface (i.e. most computers), this property should not be set. For multihoming computers, the default IP address is automatically used if this property is not set.
The IP address is a string such as in dotted notation using numbers, not domain names, such as "165.164.55.124".
const char *CkSocket_dnsLookup(HCkSocket cHandle, const char *hostname, int maxWaitMs);
Performs a DNS query to resolve a hostname to an IP address. The IP address is returned if successful. The maximum time to wait (in milliseconds) is passed in maxWaitMs. To wait indefinitely, set maxWaitMs = 0.
const char *CkSocket_httpProxyAuthMethod(HCkSocket cHandle);
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy authentication method name. Valid choices are "Basic" or "NTLM".
const char *CkSocket_httpProxyHostname(HCkSocket cHandle);
If an HTTP proxy is to be used, set this property to the HTTP proxy hostname or IPv4 address (in dotted decimal notation).
const char *CkSocket_httpProxyPassword(HCkSocket cHandle);
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy password.
const char *CkSocket_httpProxyUsername(HCkSocket cHandle);
If an HTTP proxy requiring authentication is to be used, set this property to the HTTP proxy login name.
const char *CkSocket_lastErrorHtml(HCkSocket cHandle);
Error information in HTML format for the last method called.
const char *CkSocket_lastErrorText(HCkSocket cHandle);
Error information in plain-text format for the last method called.
const char *CkSocket_lastErrorXml(HCkSocket cHandle);
Error information in XML format for the last method called.
const char *CkSocket_localIpAddress(HCkSocket cHandle);
The local IP address for a bound or connected socket.
const char *CkSocket_myIpAddress(HCkSocket cHandle);
The local IP address of the local computer. For multi-homed computers (i.e. computers with multiple IP adapters) this property returns the default IP address.
Note: This will be the internal IP address, not an external IP address. (For example, if your computer is on a LAN, it is likely to be an IP address beginning with "192.168.".
Important: Use LocalIpAddress and LocalIpPort to get the local IP/port for a bound or connected socket.
const char *CkSocket_receiveString(HCkSocket cHandle);
Receives as much data as is immediately available on a TCP/IP or SSL socket. If no data is immediately available, it waits up to MaxReadIdleMs milliseconds for data to arrive. The incoming bytes are interpreted according to the StringCharset property and returned as a string.
const char *CkSocket_receiveStringMaxN(HCkSocket cHandle, int maxBytes);
Same as ReceiveString, but limits the amount of data returned to a maximum of maxByteCount bytes.
(Receives as much data as is immediately available on the TCP/IP or SSL socket. If no data is immediately available, it waits up to MaxReadIdleMs milliseconds for data to arrive. The incoming bytes are interpreted according to the StringCharset property and returned as a string.)
const char *CkSocket_receiveStringUntilByte(HCkSocket cHandle, int byteValue);
Receives bytes on a connected SSL or non-SSL socket until a specific 1-byte value is read. Returns a string containing all the bytes up to but excluding the lookForByte.
const char *CkSocket_receiveToCRLF(HCkSocket cHandle);
Reads text from the connected TCP/IP or SSL socket until a CRLF is received. Returns the text up to and including the CRLF. The incoming bytes are interpreted according to the charset specified by the StringCharset property.
const char *CkSocket_receiveUntilMatch(HCkSocket cHandle, const char *matchStr);
Reads text from the connected TCP/IP or SSL socket until a matching string (matchStr) is received. Returns the text up to and including the matching string. As an example, to one might read the header of an HTTP request or a MIME message by reading up to the first double CRLF ("\r\n\r\n"). The incoming bytes are interpreted according to the charset specified by the StringCharset property.
const char *CkSocket_remoteIpAddress(HCkSocket cHandle);
When a socket is connected, the remote IP address of the connected peer is available in this property.
const char *CkSocket_sessionLog(HCkSocket cHandle);
Contains a log of the bytes sent and received on this socket. The KeepSessionLog property must be set to true for logging to occur.
const char *CkSocket_sessionLogEncoding(HCkSocket cHandle);
Controls how the data is encoded in the SessionLog. Possible values are "esc" and "hex". The default value is "esc".
When set to "hex", the bytes are encoded as a hexidecimalized string.
The "esc" encoding is a C-string like encoding, and is more compact than hex if most of the data to be logged is text. Printable us-ascii chars are unmodified. Common "C" control chars are represented as "\r", "\n", "\t", etc. Non-printable and byte values greater than 0x80 are escaped using a backslash and hex encoding: \xHH. Certain printable chars are backslashed: SPACE, double-quote, single-quote, etc.
const char *CkSocket_socksHostname(HCkSocket cHandle);
The SOCKS4/SOCKS5 hostname or IPv4 address (in dotted decimal notation). This property is only used if the SocksVersion property is set to 4 or 5).
const char *CkSocket_socksPassword(HCkSocket cHandle);
The SOCKS5 password (if required). The SOCKS4 protocol does not include the use of a password, so this does not apply to SOCKS4.
const char *CkSocket_socksUsername(HCkSocket cHandle);
The SOCKS4/SOCKS5 proxy username. This property is only used if the SocksVersion property is set to 4 or 5).
const char *CkSocket_sslProtocol(HCkSocket cHandle);
Selects the secure protocol to be used for secure (SSL) connections. Possible values are:
default
TLS 1.0
SSL 3.0
SSL 2.0
PCT 1.0
The default value is "default", which allows for the protocol to be selected dynamically at runtime based on the requirements of the server.
const char *CkSocket_stringCharset(HCkSocket cHandle);
A charset such as "utf-8", "windows-1252", "Shift_JIS", "iso-8859-1", etc. Methods for sending and receiving strings will use this charset as the encoding. Strings sent on the socket are first converted (if necessary) to this encoding. When reading, it is assumed that the bytes received are converted FROM this charset if necessary. This ONLY APPLIES TO THE SendString and ReceiveString methods. The default value is "ansi".
const char *CkSocket_userData(HCkSocket cHandle);
To be documented soon...
const char *CkSocket_version(HCkSocket cHandle);
The version of this component, such as "v1.0.0"
|