// CkSocketW.h: interface for the CkSocketW class. // ////////////////////////////////////////////////////////////////////// // This header is generated for Chilkat 11.3.0 #ifndef _CkSocketW_H #define _CkSocketW_H #include "chilkatDefs.h" #include "CkString.h" #include "CkClassWithCallbacksW.h" class CkTaskW; class CkJsonObjectW; class CkCertW; class CkBinDataW; class CkByteData; class CkStringBuilderW; class CkSshKeyW; class CkSshW; class CkBaseProgressW; #if !defined(__sun__) && !defined(__sun) #pragma pack (push, 8) #endif // CLASS: CkSocketW class CK_VISIBLE_PUBLIC CkSocketW : public CkClassWithCallbacksW { private: bool m_cbOwned; private: // Don't allow assignment or copying these objects. CkSocketW(const CkSocketW &); CkSocketW &operator=(const CkSocketW &); public: CkSocketW(void); virtual ~CkSocketW(void); static CkSocketW *createNew(void); CkSocketW(bool bCallbackOwned); static CkSocketW *createNew(bool bCallbackOwned); void CK_VISIBLE_PRIVATE inject(void *impl); // May be called when finished with the object to free/dispose of any // internal resources held by the object. void dispose(void); CkBaseProgressW *get_EventCallbackObject(void) const; void put_EventCallbackObject(CkBaseProgressW *progress); // BEGIN PUBLIC INTERFACE // ---------------------- // Properties // ---------------------- // When set to true, causes the currently running method to abort. Methods that // always finish quickly (i.e.have no length file operations or network // communications) are not affected. If no method is running, then this property is // automatically reset to false when the next method is called. When the abort // occurs, this property is reset to false. Both synchronous and asynchronous // method calls can be aborted. (A synchronous method call could be aborted by // setting this property from a separate thread.) bool get_AbortCurrent(void); // When set to true, causes the currently running method to abort. Methods that // always finish quickly (i.e.have no length file operations or network // communications) are not affected. If no method is running, then this property is // automatically reset to false when the next method is called. When the abort // occurs, this property is reset to false. Both synchronous and asynchronous // method calls can be aborted. (A synchronous method call could be aborted by // setting this property from a separate thread.) void put_AbortCurrent(bool newVal); // If a AcceptNextConnection method fails, this property can be checked to // determine the reason for failure. // // Note: If accepting a TLS connection, then this property can also have any of the // values listed for the ReceiveFailReason and SendFailReason properties (because // the TLS handshake involves sending/receiving on the initial TCP socket). // // Possible values are: // // 0 = Success // 1 = An async operation is in progress. // 3 = An unspecified internal failure, perhaps out-of-memory, caused the failure. // 5 = Timeout. No connections were accepted in the amount of time alotted. // 6 = The receive was aborted by the application in an event callback. // 9 = An unspecified fatal socket error occurred (less common). // 20 = Must first bind and listen on a port. // 99 = The component is not unlocked. // // Errors Relating to the SSL/TLS Handshake: // 100 = TLS internal error. // 102 = Unexpected handshake message. // 109 = Failed to read handshake messages. // 114 = Failed to send change cipher spec handshake message. // 115 = Failed to send finished handshake message. // 116 = Client's Finished message is invalid. // 117 = Unable to agree on TLS protocol version. // 118 = Unable to agree on a cipher spec. // 119 = Failed to read the client's hello message. // 120 = Failed to send handshake messages. // 121 = Failed to process client cert message. // 122 = Failed to process client cert URL message. // 123 = Failed to process client key exchange message. // 124 = Failed to process certificate verify message. // 125 = Received and rejected an SSL 2.0 connection attempt. int get_AcceptFailReason(void); // For TLS connections. Can be set to the name of an application layer protocol. // This causes the ALPN extension to be added to the TLS ClientHello with the given // ALPN protocol name. void get_AlpnProtocol(CkString &str); // For TLS connections. Can be set to the name of an application layer protocol. // This causes the ALPN extension to be added to the TLS ClientHello with the given // ALPN protocol name. const wchar_t *alpnProtocol(void); // For TLS connections. Can be set to the name of an application layer protocol. // This causes the ALPN extension to be added to the TLS ClientHello with the given // ALPN protocol name. void put_AlpnProtocol(const wchar_t *newVal); // If non-zero, limits (throttles) the receiving bandwidth to approximately this // maximum number of bytes per second. The default value of this property is 0. int get_BandwidthThrottleDown(void); // If non-zero, limits (throttles) the receiving bandwidth to approximately this // maximum number of bytes per second. The default value of this property is 0. void put_BandwidthThrottleDown(int newVal); // If non-zero, limits (throttles) the sending bandwidth to approximately this // maximum number of bytes per second. The default value of this property is 0. int get_BandwidthThrottleUp(void); // If non-zero, limits (throttles) the sending bandwidth to approximately this // maximum number of bytes per second. The default value of this property is 0. void put_BandwidthThrottleUp(int 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. bool get_BigEndian(void); // 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 put_BigEndian(bool 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 . // void get_ClientIpAddress(CkString &str); // 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 wchar_t *clientIpAddress(void); // 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 . // void put_ClientIpAddress(const wchar_t *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." // int get_ClientPort(void); // 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." // void put_ClientPort(int newVal); // 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/TLS: // 100 = TLS internal error. // 101 = Failed to send client hello. // 102 = Unexpected handshake message. // 103 = Failed to read server hello. // 104 = No server certificate. // 105 = Unexpected TLS protocol version. // 106 = Server certificate verify failed (the server certificate is expired or the cert's signature verification failed). // 107 = Unacceptable TLS protocol version. // 108 = App-defined server certificate requirements failure. // 109 = Failed to read handshake messages. // 110 = Failed to send client certificate handshake message. // 111 = Failed to send client key exchange handshake message. // 112 = Client certificate's private key not accessible. // 113 = Failed to send client cert verify handshake message. // 114 = Failed to send change cipher spec handshake message. // 115 = Failed to send finished handshake message. // 116 = Server's Finished message is invalid. // int get_ConnectFailReason(void); // Contains the number of seconds since the last call to StartTiming, otherwise // contains 0. (The StartTiming method and ElapsedSeconds property is provided for // convenience.) int get_ElapsedSeconds(void); // The interval in milliseconds between each AbortCheck event callback, which // enables an application to abort certain method calls before they complete. By // default, HeartbeatMs is set to 0 , meaning no AbortCheck event callbacks will // trigger. // // References: // 1: #AbortCheck int get_HeartbeatMs(void); // The interval in milliseconds between each AbortCheck event callback, which // enables an application to abort certain method calls before they complete. By // default, HeartbeatMs is set to 0 , meaning no AbortCheck event callbacks will // trigger. // // References: // 1: #AbortCheck void put_HeartbeatMs(int 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 get_HttpProxyAuthMethod(CkString &str); // 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 wchar_t *httpProxyAuthMethod(void); // 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 put_HttpProxyAuthMethod(const wchar_t *newVal); // The NTLM authentication domain (optional) if NTLM authentication is used. void get_HttpProxyDomain(CkString &str); // The NTLM authentication domain (optional) if NTLM authentication is used. const wchar_t *httpProxyDomain(void); // The NTLM authentication domain (optional) if NTLM authentication is used. void put_HttpProxyDomain(const wchar_t *newVal); // If this connection is effectively used to send HTTP requests, then set this // property to true when using an HTTP proxy. The default value of this property // is false. // // This is because an HTTP proxy used for other protocols (IMAP, SMTP, SSH, FTP, // etc.) can require some internal differences in behavior (i.e. how we do things). // // For example, the Chilkat REST object can use this socket object's connection via // the UseConnection method. This is a case where we know the proxied connection is // for the HTTP protocol. Therefore we should set this property to true. (See the // example below.) // bool get_HttpProxyForHttp(void); // If this connection is effectively used to send HTTP requests, then set this // property to true when using an HTTP proxy. The default value of this property // is false. // // This is because an HTTP proxy used for other protocols (IMAP, SMTP, SSH, FTP, // etc.) can require some internal differences in behavior (i.e. how we do things). // // For example, the Chilkat REST object can use this socket object's connection via // the UseConnection method. This is a case where we know the proxied connection is // for the HTTP protocol. Therefore we should set this property to true. (See the // example below.) // void put_HttpProxyForHttp(bool 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 get_HttpProxyHostname(CkString &str); // If an HTTP proxy is to be used, set this property to the HTTP proxy hostname or // IPv4 address (in dotted decimal notation). const wchar_t *httpProxyHostname(void); // If an HTTP proxy is to be used, set this property to the HTTP proxy hostname or // IPv4 address (in dotted decimal notation). void put_HttpProxyHostname(const wchar_t *newVal); // If an HTTP proxy requiring authentication is to be used, set this property to // the HTTP proxy password. void get_HttpProxyPassword(CkString &str); // If an HTTP proxy requiring authentication is to be used, set this property to // the HTTP proxy password. const wchar_t *httpProxyPassword(void); // If an HTTP proxy requiring authentication is to be used, set this property to // the HTTP proxy password. void put_HttpProxyPassword(const wchar_t *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.) int get_HttpProxyPort(void); // 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 put_HttpProxyPort(int newVal); // If an HTTP proxy requiring authentication is to be used, set this property to // the HTTP proxy login name. void get_HttpProxyUsername(CkString &str); // If an HTTP proxy requiring authentication is to be used, set this property to // the HTTP proxy login name. const wchar_t *httpProxyUsername(void); // If an HTTP proxy requiring authentication is to be used, set this property to // the HTTP proxy login name. void put_HttpProxyUsername(const wchar_t *newVal); // Returns true if the socket is connected. Otherwise returns false. // // Note: In general, this property indicates the last known state of the socket. // For example, if the socket is connected, and your application does not read or // write the socket, then IsConnected will remain true. This property is updated // when your application tries to read or write and discovers that the socket is no // longer connected. It is also updated if your application explicitly closes the // socket. // bool get_IsConnected(void); // Controls whether the SO_KEEPALIVE socket option is used for the underlying // TCP/IP socket. The default value is true. bool get_KeepAlive(void); // Controls whether the SO_KEEPALIVE socket option is used for the underlying // TCP/IP socket. The default value is true. void put_KeepAlive(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). bool get_KeepSessionLog(void); // 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 put_KeepSessionLog(bool newVal); // 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. bool get_LastMethodFailed(void); // If set to true, then a socket that listens for incoming connections (via the // BindAndList and AcceptNextConnection method calls) will use IPv6 and not IPv4. // The default value is false for IPv4. bool get_ListenIpv6(void); // If set to true, then a socket that listens for incoming connections (via the // BindAndList and AcceptNextConnection method calls) will use IPv6 and not IPv4. // The default value is false for IPv4. void put_ListenIpv6(bool newVal); // The BindAndListen method will find a random unused port to listen on if you bind // to port 0. This chosen listen port is available via this property. int get_ListenPort(void); // The local IP address for a bound or connected socket. void get_LocalIpAddress(CkString &str); // The local IP address for a bound or connected socket. const wchar_t *localIpAddress(void); // The local port for a bound or connected socket. int get_LocalPort(void); // 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. // // This applies to all methods that read from the socket, and also any other // methods that read on the socket, such as SshOpenTunnel. // int get_MaxReadIdleMs(void); // 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. // // This applies to all methods that read from the socket, and also any other // methods that read on the socket, such as SshOpenTunnel. // void put_MaxReadIdleMs(int 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. int get_MaxSendIdleMs(void); // 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 put_MaxSendIdleMs(int newVal); // 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. // void get_MyIpAddress(CkString &str); // 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 wchar_t *myIpAddress(void); // Returns the number of bytes that are immediately available for reading on a // connected socket. For TLS connections, this includes the overhead for TLS // protocol records. int get_NumBytesAvailable(void); // If the socket is the server-side of an SSL/TLS connection, the property // represents the number of client-side certificates received during the SSL/TLS // handshake (i.e. connection process). Each client-side cert may be retrieved by // calling the GetReceivedClientCert method and passing an integer index value from // 0 to N-1, where N is the number of client certs received. // // Note: A client only sends a certificate if 2-way SSL/TLS is required. In other // words, if the server demands a certificate from the client. // // Important: This property should be examined on the socket object that is // returned by AcceptNextConnection. // int get_NumReceivedClientCerts(void); // 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. int get_NumSocketsInSet(void); // If connected as an SSL/TLS client to an SSL/TLS server where the server requires // a client-side certificate for authentication, then this property contains the // number of acceptable certificate authorities sent by the server during // connection establishment handshake. The GetSslAcceptableClientCaDn method may be // called to get the Distinguished Name (DN) of each acceptable CA. int get_NumSslAcceptableClientCAs(void); // 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. int get_ObjectId(void); // This property is only valid in programming environment and languages that allow // for event callbacks. // // Sets the value to be defined as 100% complete for the purpose of PercentDone // event callbacks. The defaut value of 100 means that at most 100 event // PercentDone callbacks will occur in a method that (1) is event enabled and (2) // is such that it is possible to measure progress as a percentage completed. This // property may be set to larger numbers to get more fine-grained PercentDone // callbacks. For example, setting this property equal to 1000 will provide // callbacks with .1 percent granularity. For example, a value of 453 would // indicate 45.3% competed. This property is clamped to a minimum value of 10, and // a maximum value of 100000. // int get_PercentDoneScale(void); // This property is only valid in programming environment and languages that allow // for event callbacks. // // Sets the value to be defined as 100% complete for the purpose of PercentDone // event callbacks. The defaut value of 100 means that at most 100 event // PercentDone callbacks will occur in a method that (1) is event enabled and (2) // is such that it is possible to measure progress as a percentage completed. This // property may be set to larger numbers to get more fine-grained PercentDone // callbacks. For example, setting this property equal to 1000 will provide // callbacks with .1 percent granularity. For example, a value of 453 would // indicate 45.3% competed. This property is clamped to a minimum value of 10, and // a maximum value of 100000. // void put_PercentDoneScale(int newVal); // If the socket is used for initiating connections, then this property behaves as // follows: When connecting to a domain name, the automatic DNS lookup could result // in both IPv4 and IPv6 addresses. If this property is true, then the IPv6 // address is chosen, otherwise the IPv4 address is chosen. The default value of // this property is false, which will choose IPv4 over IPv6. // // If the socket is used for listening and receiving connections, then this // property controls whether to listen on IPv6 or IPv4. If this property is true, // then IPv6 connections can be accepted, otherwise only IPv4 connections can be // accepted. (Note: Chilkat was updated in v9.5.0.97 to enable dual-stack support, // where a server can handle both IPv6 and IPv4 traffic using a single socket. // Prior to v9.5.0.97, setting this property to true had the effect that only // IPv6 connections could be accepted.) // bool get_PreferIpv6(void); // If the socket is used for initiating connections, then this property behaves as // follows: When connecting to a domain name, the automatic DNS lookup could result // in both IPv4 and IPv6 addresses. If this property is true, then the IPv6 // address is chosen, otherwise the IPv4 address is chosen. The default value of // this property is false, which will choose IPv4 over IPv6. // // If the socket is used for listening and receiving connections, then this // property controls whether to listen on IPv6 or IPv4. If this property is true, // then IPv6 connections can be accepted, otherwise only IPv4 connections can be // accepted. (Note: Chilkat was updated in v9.5.0.97 to enable dual-stack support, // where a server can handle both IPv6 and IPv4 traffic using a single socket. // Prior to v9.5.0.97, setting this property to true had the effect that only // IPv6 connections could be accepted.) // void put_PreferIpv6(bool newVal); // Returns the cumulative receive rate in bytes per second. The measurement // includes the overhead bytes for protocols such as TLS or SSH tunneling. For // example, if 1000 application bytes are received, the actual number of raw bytes // received on a TLS connection is greater. This property measures the actual // number of raw bytes received in a given time period. The ResetPerf method can be // called to reset this property value and to begin the performance measurement // afresh. int get_RcvBytesPerSec(void); // Any method that receives data will increase the value of this property by the // number of bytes received. The application may reset this property to 0 at any // point. It is provided as a way to keep count of the total number of bytes // received on a socket connection, regardless of which method calls are used to // receive the data. // // Note: The ReceivedCount may be larger than the number of bytes returned by some // methods. For methods such as ReceiveUntilMatch, the excess received on the // socket (beyond the match), is buffered by Chilkat for subsequent method calls. // The ReceivedCount is updated based on the actual number of bytes received on the // underlying socket in real-time. (The ReceivedCount does not include the overhead // bytes associated with the TLS and/or SSH protocols. // int get_ReceivedCount(void); // Any method that receives data will increase the value of this property by the // number of bytes received. The application may reset this property to 0 at any // point. It is provided as a way to keep count of the total number of bytes // received on a socket connection, regardless of which method calls are used to // receive the data. // // Note: The ReceivedCount may be larger than the number of bytes returned by some // methods. For methods such as ReceiveUntilMatch, the excess received on the // socket (beyond the match), is buffered by Chilkat for subsequent method calls. // The ReceivedCount is updated based on the actual number of bytes received on the // underlying socket in real-time. (The ReceivedCount does not include the overhead // bytes associated with the TLS and/or SSH protocols. // void put_ReceivedCount(int newVal); // Contains the last integer received via a call to ReceiveByte, ReceiveInt16, or // ReceiveInt32. int get_ReceivedInt(void); // Contains the last integer received via a call to ReceiveByte, ReceiveInt16, or // ReceiveInt32. void put_ReceivedInt(int newVal); // If a Receive method fails, this property can be checked to determine the reason // for failure. // // Possible values are:0 = Success // 1 = An async receive operation is already in progress. // 2 = The socket is not connected, such as if it was never connected, or if the connection was previously lost. // 3 = An unspecified internal failure, perhaps out-of-memory, caused the failure. // 4 = Invalid parameters were passed to the receive method call. // 5 = Timeout. Data stopped arriving for more than the amount of time specified by the MaxReadIdleMs property. // 6 = The receive was aborted by the application in an event callback. // 7 = The connection was lost -- the remote peer reset the connection. (The connection was forcibly closed by the peer.) // 8 = An established connection was aborted by the software in your host machine. (See https://www.chilkatsoft.com/p/p_299.asp ) // 9 = An unspecified fatal socket error occurred (less common). // 10 = The connection was closed by the peer. // int get_ReceiveFailReason(void); // 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. int get_ReceivePacketSize(void); // 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 put_ReceivePacketSize(int newVal); // When a socket is connected, the remote IP address of the connected peer is // available in this property. void get_RemoteIpAddress(CkString &str); // When a socket is connected, the remote IP address of the connected peer is // available in this property. const wchar_t *remoteIpAddress(void); // When a socket is connected, the remote port of the connected peer is available // in this property. int get_RemotePort(void); // If true, then the SSL/TLS client will verify the server's SSL certificate. The // certificate is expired, or if the cert's signature is invalid, the connection is // not allowed. The default value of this property is false. bool get_RequireSslCertVerify(void); // If true, then the SSL/TLS client will verify the server's SSL certificate. The // certificate is expired, or if the cert's signature is invalid, the connection is // not allowed. The default value of this property is false. void put_RequireSslCertVerify(bool 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 get_SelectorIndex(void); // 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. void put_SelectorIndex(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 get_SelectorReadIndex(void); // 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: void put_SelectorReadIndex(int newVal); // When SelectForWriting returns a number greater than 0 indicating that one or // more sockets are ready for writing, this property is used to select the socket // in the ready set for writing. int get_SelectorWriteIndex(void); // When SelectForWriting returns a number greater than 0 indicating that one or // more sockets are ready for writing, this property is used to select the socket // in the ready set for writing. void put_SelectorWriteIndex(int newVal); // Returns the cumulative send rate in bytes per second. The measurement includes // the overhead bytes for protocols such as TLS or SSH tunneling. For example, if // 1000 application bytes are sent, the actual number of raw bytes sent on a TLS // connection is greater. This property measures the actual number of raw bytes // sent in a given time period. The ResetPerf method can be called to reset this // property value and to begin the performance measurement afresh. int get_SendBytesPerSec(void); // If a Send method fails, this property can be checked to determine the reason for // failure. // // Possible values are:0 = Success // 1 = An async receive operation is already in progress. // 2 = The socket is not connected, such as if it was never connected, or if the connection was previously lost. // 3 = An unspecified internal failure, perhaps out-of-memory, caused the failure. // 4 = Invalid parameters were passed to the receive method call. // 5 = Timeout. Data stopped arriving for more than the amount of time specified by the MaxReadIdleMs property. // 6 = The receive was aborted by the application in an event callback. // 7 = The connection was lost -- the remote peer reset the connection. (The connection was forcibly closed by the peer.) // 8 = An established connection was aborted by the software in your host machine. (See https://www.chilkatsoft.com/p/p_299.asp ) // 9 = An unspecified fatal socket error occurred (less common). // 10 = The connection was closed by the peer. // 11 = Decoding error (possible in SendString when coverting to the StringCharset, or in SendBytesENC). // int get_SendFailReason(void); // 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.) int get_SendPacketSize(void); // 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 put_SendPacketSize(int newVal); // 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 get_SessionLog(CkString &str); // 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 wchar_t *sessionLog(void); // 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. // void get_SessionLogEncoding(CkString &str); // 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 wchar_t *sessionLogEncoding(void); // 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. // void put_SessionLogEncoding(const wchar_t *newVal); // Specifies the SNI hostname to be used in the TLS ClientHello. This property is // only needed when the domain is specified via a dotted IP address and an SNI // hostname is desired. (Normally, Chilkat automatically uses the domain name in // the SNI hostname TLS ClientHello extension.) void get_SniHostname(CkString &str); // Specifies the SNI hostname to be used in the TLS ClientHello. This property is // only needed when the domain is specified via a dotted IP address and an SNI // hostname is desired. (Normally, Chilkat automatically uses the domain name in // the SNI hostname TLS ClientHello extension.) const wchar_t *sniHostname(void); // Specifies the SNI hostname to be used in the TLS ClientHello. This property is // only needed when the domain is specified via a dotted IP address and an SNI // hostname is desired. (Normally, Chilkat automatically uses the domain name in // the SNI hostname TLS ClientHello extension.) void put_SniHostname(const wchar_t *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 get_SocksHostname(CkString &str); // 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 wchar_t *socksHostname(void); // 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 put_SocksHostname(const wchar_t *newVal); // The SOCKS5 password (if required). The SOCKS4 protocol does not include the use // of a password, so this does not apply to SOCKS4. void get_SocksPassword(CkString &str); // The SOCKS5 password (if required). The SOCKS4 protocol does not include the use // of a password, so this does not apply to SOCKS4. const wchar_t *socksPassword(void); // The SOCKS5 password (if required). The SOCKS4 protocol does not include the use // of a password, so this does not apply to SOCKS4. void put_SocksPassword(const wchar_t *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). int get_SocksPort(void); // 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 put_SocksPort(int newVal); // The SOCKS4/SOCKS5 proxy username. This property is only used if the SocksVersion // property is set to 4 or 5). void get_SocksUsername(CkString &str); // The SOCKS4/SOCKS5 proxy username. This property is only used if the SocksVersion // property is set to 4 or 5). const wchar_t *socksUsername(void); // The SOCKS4/SOCKS5 proxy username. This property is only used if the SocksVersion // property is set to 4 or 5). void put_SocksUsername(const wchar_t *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. // int get_SocksVersion(void); // 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. // void put_SocksVersion(int newVal); // Sets the receive buffer size socket option. Normally, this property should be // left unchanged. The default value is 4194304. // // This property can be increased if download performance seems slow. It is // recommended to be a multiple of 4096. // int get_SoRcvBuf(void); // Sets the receive buffer size socket option. Normally, this property should be // left unchanged. The default value is 4194304. // // This property can be increased if download performance seems slow. It is // recommended to be a multiple of 4096. // void put_SoRcvBuf(int newVal); // Sets the SO_REUSEADDR socket option for a socket that will bind to a port and // listen for incoming connections. The default value is true, meaning that the // SO_REUSEADDR socket option is set. If the socket option must be unset, set this // property equal to false prior to calling BindAndListen or InitSslServer. bool get_SoReuseAddr(void); // Sets the SO_REUSEADDR socket option for a socket that will bind to a port and // listen for incoming connections. The default value is true, meaning that the // SO_REUSEADDR socket option is set. If the socket option must be unset, set this // property equal to false prior to calling BindAndListen or InitSslServer. void put_SoReuseAddr(bool newVal); // Sets the send buffer size socket option. Normally, this property should be left // unchanged. The default value is 262144. // // This property can be increased if upload performance seems slow. It is // recommended to be a multiple of 4096. Testing with sizes such as 512K and 1MB is // reasonable. // int get_SoSndBuf(void); // Sets the send buffer size socket option. Normally, this property should be left // unchanged. The default value is 262144. // // This property can be increased if upload performance seems slow. It is // recommended to be a multiple of 4096. Testing with sizes such as 512K and 1MB is // reasonable. // void put_SoSndBuf(int newVal); // Set this property to true if SSL/TLS is required for accepted connections // (AcceptNextConnection). The default value is false. // // Note: This property should have been more precisely named RequireSslClient . It // is a property that if set to true, requires all accepted connections use // SSL/TLS. If a client attempts to connect but cannot establish the TLS // connection, then it is not accepted. This property is not meant to reflect the // current state of the connection. // // The TlsVersion property shows the current or last negotiated TLS version of the // connection. The TlsVersion will be empty for a non-SSL/TLS connection. // bool get_Ssl(void); // Set this property to true if SSL/TLS is required for accepted connections // (AcceptNextConnection). The default value is false. // // Note: This property should have been more precisely named RequireSslClient . It // is a property that if set to true, requires all accepted connections use // SSL/TLS. If a client attempts to connect but cannot establish the TLS // connection, then it is not accepted. This property is not meant to reflect the // current state of the connection. // // The TlsVersion property shows the current or last negotiated TLS version of the // connection. The TlsVersion will be empty for a non-SSL/TLS connection. // void put_Ssl(bool newVal); // Provides a means for setting a list of ciphers that are allowed for SSL/TLS // connections. The default (empty string) indicates that all implemented ciphers // are possible. The TLS ciphers supported in Chilkat v9.5.0.55 and later are:TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 // TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 // TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 // TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA // TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 // TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA // TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 // TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 // TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 // TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA // TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 // TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 // TLS_DHE_RSA_WITH_AES_256_CBC_SHA // TLS_RSA_WITH_AES_256_CBC_SHA256 // TLS_RSA_WITH_AES_256_GCM_SHA384 // TLS_RSA_WITH_AES_256_CBC_SHA // TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 // TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 // TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 // TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA // TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 // TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 // TLS_DHE_RSA_WITH_AES_128_CBC_SHA // TLS_RSA_WITH_AES_128_CBC_SHA256 // TLS_RSA_WITH_AES_128_GCM_SHA256 // TLS_RSA_WITH_AES_128_CBC_SHA // TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA // TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA // TLS_RSA_WITH_3DES_EDE_CBC_SHA // TLS_ECDHE_RSA_WITH_RC4_128_SHA // TLS_RSA_WITH_RC4_128_SHA // TLS_RSA_WITH_RC4_128_MD5 // TLS_DHE_RSA_WITH_DES_CBC_SHA // TLS_RSA_WITH_DES_CBC_SHA // To restrict SSL/TLS connections to one or more specific ciphers, set this // property to a comma-separated list of ciphers such as // TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 . // The order should be in terms of preference, with the preferred algorithms listed // first. (Note that the client cannot specifically choose the algorithm is picked // because it is the server that chooses. The client simply provides the server // with a list from which to choose.) // // The property can also disallow connections with servers having certificates with // RSA keys less than a certain size. By default, server certificates having RSA // keys of 512 bits or greater are allowed. Add the keyword rsa1024 to disallow // connections with servers having keys smaller than 1024 bits. Add the keyword // rsa2048 to disallow connections with servers having keys smaller than 2048 bits. // // Note: Prior to Chilkat v9.5.0.55, it was not possible to explicitly list allowed // cipher suites. The deprecated means for indicating allowed ciphers was both // incomplete and unprecise. For example, the following keywords could be listed to // allow matching ciphers: aes256-cbc , aes128-cbc , 3des-cbc , and rc4 . These // keywords will still be recognized, but programs should be updated to explicitly // list the allowed ciphers. // // secure-renegotiation: Starting in Chilkat v9.5.0.55, the keyword // secure-renegotiation may be added to require that all renegotions be done // securely (as per RFC 5746). // // best-practices: Starting in Chilkat v9.5.0.55, this property may be set to the // single keyword best-practices . This will allow ciphers based on the current // best practices. As new versions of Chilkat are released, the best practices may // change. Changes will be noted here. The current best practices are: // // * If the server uses an RSA key, it must be 1024 bits or greater. // * All renegotations must be secure renegotiations. // * All ciphers using RC4, DES, or 3DES are disallowed. // // Example: The following string would restrict to 2 specific cipher suites, // require RSA keys to be 1024 bits or greater, and require secure renegotiations: // TLS_DHE_RSA_WITH_AES_256_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA, rsa1024, // secure-renegotiation // void get_SslAllowedCiphers(CkString &str); // Provides a means for setting a list of ciphers that are allowed for SSL/TLS // connections. The default (empty string) indicates that all implemented ciphers // are possible. The TLS ciphers supported in Chilkat v9.5.0.55 and later are:TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 // TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 // TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 // TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA // TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 // TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA // TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 // TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 // TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 // TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA // TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 // TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 // TLS_DHE_RSA_WITH_AES_256_CBC_SHA // TLS_RSA_WITH_AES_256_CBC_SHA256 // TLS_RSA_WITH_AES_256_GCM_SHA384 // TLS_RSA_WITH_AES_256_CBC_SHA // TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 // TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 // TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 // TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA // TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 // TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 // TLS_DHE_RSA_WITH_AES_128_CBC_SHA // TLS_RSA_WITH_AES_128_CBC_SHA256 // TLS_RSA_WITH_AES_128_GCM_SHA256 // TLS_RSA_WITH_AES_128_CBC_SHA // TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA // TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA // TLS_RSA_WITH_3DES_EDE_CBC_SHA // TLS_ECDHE_RSA_WITH_RC4_128_SHA // TLS_RSA_WITH_RC4_128_SHA // TLS_RSA_WITH_RC4_128_MD5 // TLS_DHE_RSA_WITH_DES_CBC_SHA // TLS_RSA_WITH_DES_CBC_SHA // To restrict SSL/TLS connections to one or more specific ciphers, set this // property to a comma-separated list of ciphers such as // TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 . // The order should be in terms of preference, with the preferred algorithms listed // first. (Note that the client cannot specifically choose the algorithm is picked // because it is the server that chooses. The client simply provides the server // with a list from which to choose.) // // The property can also disallow connections with servers having certificates with // RSA keys less than a certain size. By default, server certificates having RSA // keys of 512 bits or greater are allowed. Add the keyword rsa1024 to disallow // connections with servers having keys smaller than 1024 bits. Add the keyword // rsa2048 to disallow connections with servers having keys smaller than 2048 bits. // // Note: Prior to Chilkat v9.5.0.55, it was not possible to explicitly list allowed // cipher suites. The deprecated means for indicating allowed ciphers was both // incomplete and unprecise. For example, the following keywords could be listed to // allow matching ciphers: aes256-cbc , aes128-cbc , 3des-cbc , and rc4 . These // keywords will still be recognized, but programs should be updated to explicitly // list the allowed ciphers. // // secure-renegotiation: Starting in Chilkat v9.5.0.55, the keyword // secure-renegotiation may be added to require that all renegotions be done // securely (as per RFC 5746). // // best-practices: Starting in Chilkat v9.5.0.55, this property may be set to the // single keyword best-practices . This will allow ciphers based on the current // best practices. As new versions of Chilkat are released, the best practices may // change. Changes will be noted here. The current best practices are: // // * If the server uses an RSA key, it must be 1024 bits or greater. // * All renegotations must be secure renegotiations. // * All ciphers using RC4, DES, or 3DES are disallowed. // // Example: The following string would restrict to 2 specific cipher suites, // require RSA keys to be 1024 bits or greater, and require secure renegotiations: // TLS_DHE_RSA_WITH_AES_256_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA, rsa1024, // secure-renegotiation // const wchar_t *sslAllowedCiphers(void); // Provides a means for setting a list of ciphers that are allowed for SSL/TLS // connections. The default (empty string) indicates that all implemented ciphers // are possible. The TLS ciphers supported in Chilkat v9.5.0.55 and later are:TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 // TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 // TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 // TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA // TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 // TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA // TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 // TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 // TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 // TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA // TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 // TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 // TLS_DHE_RSA_WITH_AES_256_CBC_SHA // TLS_RSA_WITH_AES_256_CBC_SHA256 // TLS_RSA_WITH_AES_256_GCM_SHA384 // TLS_RSA_WITH_AES_256_CBC_SHA // TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 // TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 // TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 // TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA // TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 // TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 // TLS_DHE_RSA_WITH_AES_128_CBC_SHA // TLS_RSA_WITH_AES_128_CBC_SHA256 // TLS_RSA_WITH_AES_128_GCM_SHA256 // TLS_RSA_WITH_AES_128_CBC_SHA // TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA // TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA // TLS_RSA_WITH_3DES_EDE_CBC_SHA // TLS_ECDHE_RSA_WITH_RC4_128_SHA // TLS_RSA_WITH_RC4_128_SHA // TLS_RSA_WITH_RC4_128_MD5 // TLS_DHE_RSA_WITH_DES_CBC_SHA // TLS_RSA_WITH_DES_CBC_SHA // To restrict SSL/TLS connections to one or more specific ciphers, set this // property to a comma-separated list of ciphers such as // TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 . // The order should be in terms of preference, with the preferred algorithms listed // first. (Note that the client cannot specifically choose the algorithm is picked // because it is the server that chooses. The client simply provides the server // with a list from which to choose.) // // The property can also disallow connections with servers having certificates with // RSA keys less than a certain size. By default, server certificates having RSA // keys of 512 bits or greater are allowed. Add the keyword rsa1024 to disallow // connections with servers having keys smaller than 1024 bits. Add the keyword // rsa2048 to disallow connections with servers having keys smaller than 2048 bits. // // Note: Prior to Chilkat v9.5.0.55, it was not possible to explicitly list allowed // cipher suites. The deprecated means for indicating allowed ciphers was both // incomplete and unprecise. For example, the following keywords could be listed to // allow matching ciphers: aes256-cbc , aes128-cbc , 3des-cbc , and rc4 . These // keywords will still be recognized, but programs should be updated to explicitly // list the allowed ciphers. // // secure-renegotiation: Starting in Chilkat v9.5.0.55, the keyword // secure-renegotiation may be added to require that all renegotions be done // securely (as per RFC 5746). // // best-practices: Starting in Chilkat v9.5.0.55, this property may be set to the // single keyword best-practices . This will allow ciphers based on the current // best practices. As new versions of Chilkat are released, the best practices may // change. Changes will be noted here. The current best practices are: // // * If the server uses an RSA key, it must be 1024 bits or greater. // * All renegotations must be secure renegotiations. // * All ciphers using RC4, DES, or 3DES are disallowed. // // Example: The following string would restrict to 2 specific cipher suites, // require RSA keys to be 1024 bits or greater, and require secure renegotiations: // TLS_DHE_RSA_WITH_AES_256_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA, rsa1024, // secure-renegotiation // void put_SslAllowedCiphers(const wchar_t *newVal); // Selects the secure protocol to be used for secure (SSL/TLS) connections. // Possible values are: // // default // TLS 1.3 // TLS 1.2 // TLS 1.1 // TLS 1.0 // SSL 3.0 // TLS 1.3 or higher // TLS 1.2 or higher // TLS 1.1 or higher // TLS 1.0 or higher // // // The default value is default which will choose the, which allows for the // protocol to be selected dynamically at runtime based on the requirements of the // server. Choosing an exact protocol will cause the connection to fail unless that // exact protocol is negotiated. It is better to choose X or higher than an exact // protocol. The default is effectively SSL 3.0 or higher . // // Note: Chilkat does not yet implement TLS 1.3 for the server-side of the TLS // protocol. Chilkat can do TLS 1.3 on the client-side, such as when connecting to // servers, but not when acting as a server and receiving/accepting TLS // connections. // void get_SslProtocol(CkString &str); // Selects the secure protocol to be used for secure (SSL/TLS) connections. // Possible values are: // // default // TLS 1.3 // TLS 1.2 // TLS 1.1 // TLS 1.0 // SSL 3.0 // TLS 1.3 or higher // TLS 1.2 or higher // TLS 1.1 or higher // TLS 1.0 or higher // // // The default value is default which will choose the, which allows for the // protocol to be selected dynamically at runtime based on the requirements of the // server. Choosing an exact protocol will cause the connection to fail unless that // exact protocol is negotiated. It is better to choose X or higher than an exact // protocol. The default is effectively SSL 3.0 or higher . // // Note: Chilkat does not yet implement TLS 1.3 for the server-side of the TLS // protocol. Chilkat can do TLS 1.3 on the client-side, such as when connecting to // servers, but not when acting as a server and receiving/accepting TLS // connections. // const wchar_t *sslProtocol(void); // Selects the secure protocol to be used for secure (SSL/TLS) connections. // Possible values are: // // default // TLS 1.3 // TLS 1.2 // TLS 1.1 // TLS 1.0 // SSL 3.0 // TLS 1.3 or higher // TLS 1.2 or higher // TLS 1.1 or higher // TLS 1.0 or higher // // // The default value is default which will choose the, which allows for the // protocol to be selected dynamically at runtime based on the requirements of the // server. Choosing an exact protocol will cause the connection to fail unless that // exact protocol is negotiated. It is better to choose X or higher than an exact // protocol. The default is effectively SSL 3.0 or higher . // // Note: Chilkat does not yet implement TLS 1.3 for the server-side of the TLS // protocol. Chilkat can do TLS 1.3 on the client-side, such as when connecting to // servers, but not when acting as a server and receiving/accepting TLS // connections. // void put_SslProtocol(const wchar_t *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 . void get_StringCharset(CkString &str); // 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 wchar_t *stringCharset(void); // 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 . void put_StringCharset(const wchar_t *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. bool get_TcpNoDelay(void); // 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 put_TcpNoDelay(bool newVal); // Contains the current or last negotiated TLS cipher suite. If no TLS connection // has yet to be established, or if a connection as attempted and failed, then this // will be empty. A sample cipher suite string looks like this: // TLS_DHE_RSA_WITH_AES_256_CBC_SHA256. void get_TlsCipherSuite(CkString &str); // Contains the current or last negotiated TLS cipher suite. If no TLS connection // has yet to be established, or if a connection as attempted and failed, then this // will be empty. A sample cipher suite string looks like this: // TLS_DHE_RSA_WITH_AES_256_CBC_SHA256. const wchar_t *tlsCipherSuite(void); // Specifies a set of pins for Public Key Pinning for TLS connections. This // property lists the expected SPKI fingerprints for the server certificates. If // the server's certificate (sent during the TLS handshake) does not match any of // the SPKI fingerprints, then the TLS handshake is aborted and the connection // fails. The format of this string property is as follows:hash_algorithm, encoding, SPKI_fingerprint_1, SPKI_fingerprint_2, ... // For example, the following string specifies a single sha256 base64-encoded SPKI // fingerprint:"sha256, base64, lKg1SIqyhPSK19tlPbjl8s02yChsVTDklQpkMCHvsTE=" // This example specifies two SPKI fingerprints:"sha256, base64, 4t37LpnGmrMEAG8HEz9yIrnvJV2euVRwCLb9EH5WZyI=, 68b0G5iqMvWVWvUCjMuhLEyekM5729PadtnU5tdXZKs=" // Any of the following hash algorithms are allowed:.sha1, sha256, sha384, sha512, // md2, md5, haval, ripemd128, ripemd160,ripemd256, or ripemd320. // // The following encodings are allowed: base64, hex, and any of the encodings // indicated in the link below. // void get_TlsPinSet(CkString &str); // Specifies a set of pins for Public Key Pinning for TLS connections. This // property lists the expected SPKI fingerprints for the server certificates. If // the server's certificate (sent during the TLS handshake) does not match any of // the SPKI fingerprints, then the TLS handshake is aborted and the connection // fails. The format of this string property is as follows:hash_algorithm, encoding, SPKI_fingerprint_1, SPKI_fingerprint_2, ... // For example, the following string specifies a single sha256 base64-encoded SPKI // fingerprint:"sha256, base64, lKg1SIqyhPSK19tlPbjl8s02yChsVTDklQpkMCHvsTE=" // This example specifies two SPKI fingerprints:"sha256, base64, 4t37LpnGmrMEAG8HEz9yIrnvJV2euVRwCLb9EH5WZyI=, 68b0G5iqMvWVWvUCjMuhLEyekM5729PadtnU5tdXZKs=" // Any of the following hash algorithms are allowed:.sha1, sha256, sha384, sha512, // md2, md5, haval, ripemd128, ripemd160,ripemd256, or ripemd320. // // The following encodings are allowed: base64, hex, and any of the encodings // indicated in the link below. // const wchar_t *tlsPinSet(void); // Specifies a set of pins for Public Key Pinning for TLS connections. This // property lists the expected SPKI fingerprints for the server certificates. If // the server's certificate (sent during the TLS handshake) does not match any of // the SPKI fingerprints, then the TLS handshake is aborted and the connection // fails. The format of this string property is as follows:hash_algorithm, encoding, SPKI_fingerprint_1, SPKI_fingerprint_2, ... // For example, the following string specifies a single sha256 base64-encoded SPKI // fingerprint:"sha256, base64, lKg1SIqyhPSK19tlPbjl8s02yChsVTDklQpkMCHvsTE=" // This example specifies two SPKI fingerprints:"sha256, base64, 4t37LpnGmrMEAG8HEz9yIrnvJV2euVRwCLb9EH5WZyI=, 68b0G5iqMvWVWvUCjMuhLEyekM5729PadtnU5tdXZKs=" // Any of the following hash algorithms are allowed:.sha1, sha256, sha384, sha512, // md2, md5, haval, ripemd128, ripemd160,ripemd256, or ripemd320. // // The following encodings are allowed: base64, hex, and any of the encodings // indicated in the link below. // void put_TlsPinSet(const wchar_t *newVal); // Contains the current or last negotiated TLS protocol version. If no TLS // connection has yet to be established, or if a connection as attempted and // failed, then this will be empty. Possible values are SSL 3.0 , TLS 1.0 , TLS 1.1 // , TLS 1.2 , and TLS 1.3 . void get_TlsVersion(CkString &str); // Contains the current or last negotiated TLS protocol version. If no TLS // connection has yet to be established, or if a connection as attempted and // failed, then this will be empty. Possible values are SSL 3.0 , TLS 1.0 , TLS 1.1 // , TLS 1.2 , and TLS 1.3 . const wchar_t *tlsVersion(void); // This is a catch-all property to be used for uncommon needs. This property // defaults to the empty string and should typically remain empty. Can be set to a // list of the following comma separated keywords: // * ProtectFromVpn - Introduced in v9.5.0.80. On Android systems, will bypass // any VPN that may be installed or active. // * EnableTls13 - Introduced in v9.5.0.82. Causes TLS 1.3 to be offered in the // ClientHello of the TLS protocol, allowing the server to select TLS 1.3 for the // session. Future versions of Chilkat will enable TLS 1.3 by default. This option // is only necessary in v9.5.0.82 if TLS 1.3 is desired. // * ListenAllNetworkInterfaces - Introduced in v11.2.0. Causes the listener // socket to bind to 0.0.0.0 instead of 127.0.0.1. void get_UncommonOptions(CkString &str); // This is a catch-all property to be used for uncommon needs. This property // defaults to the empty string and should typically remain empty. Can be set to a // list of the following comma separated keywords: // * ProtectFromVpn - Introduced in v9.5.0.80. On Android systems, will bypass // any VPN that may be installed or active. // * EnableTls13 - Introduced in v9.5.0.82. Causes TLS 1.3 to be offered in the // ClientHello of the TLS protocol, allowing the server to select TLS 1.3 for the // session. Future versions of Chilkat will enable TLS 1.3 by default. This option // is only necessary in v9.5.0.82 if TLS 1.3 is desired. // * ListenAllNetworkInterfaces - Introduced in v11.2.0. Causes the listener // socket to bind to 0.0.0.0 instead of 127.0.0.1. const wchar_t *uncommonOptions(void); // This is a catch-all property to be used for uncommon needs. This property // defaults to the empty string and should typically remain empty. Can be set to a // list of the following comma separated keywords: // * ProtectFromVpn - Introduced in v9.5.0.80. On Android systems, will bypass // any VPN that may be installed or active. // * EnableTls13 - Introduced in v9.5.0.82. Causes TLS 1.3 to be offered in the // ClientHello of the TLS protocol, allowing the server to select TLS 1.3 for the // session. Future versions of Chilkat will enable TLS 1.3 by default. This option // is only necessary in v9.5.0.82 if TLS 1.3 is desired. // * ListenAllNetworkInterfaces - Introduced in v11.2.0. Causes the listener // socket to bind to 0.0.0.0 instead of 127.0.0.1. void put_UncommonOptions(const wchar_t *newVal); // Provides a way to store text data with the socket object. The UserData is purely // for convenience and is not involved in the socket communications in any way. An // application might use this property to keep extra information associated with // the socket. void get_UserData(CkString &str); // Provides a way to store text data with the socket object. The UserData is purely // for convenience and is not involved in the socket communications in any way. An // application might use this property to keep extra information associated with // the socket. const wchar_t *userData(void); // Provides a way to store text data with the socket object. The UserData is purely // for convenience and is not involved in the socket communications in any way. An // application might use this property to keep extra information associated with // the socket. void put_UserData(const wchar_t *newVal); // ---------------------- // Methods // ---------------------- // This method accepts the next incoming connection and stores the result in socket. // maxWaitMs specifies the maximum wait time in milliseconds; set it to 0 for an // indefinite wait. // // Important: For SSL/TLS connections, the TLS handshake, which establishes // algorithms and a shared key, is part of the connection process. This involves // several client-server message exchanges governed by the MaxReadIdleMs and // MaxSendIdleMs settings. If these are set to 0 (the default unless changed by // your application), the method may hang indefinitely during the handshake. Ensure // these properties are set appropriately before using this method. // bool AcceptNext(int maxWaitMs, CkSocketW &socket); // Creates an asynchronous task to call the AcceptNext method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *AcceptNextAsync(int maxWaitMs, CkSocketW &socket); // Applications should instead call AcceptNext . // // 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. // // The caller is responsible for deleting the object returned by this method. CkSocketW *AcceptNextConnection(int maxWaitMs); // Creates an asynchronous task to call the AcceptNextConnection method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *AcceptNextConnectionAsync(int maxWaitMs); // If this object is a server-side socket accepting SSL/TLS connections, and wishes // to require a client-side certificate for authentication, then it should make one // or more calls to this method to identify the CA's it will accept for client-side // certificates. // // If no CA DN's are added by this method, then client certificates from any root // CA are accepted. // // Important: If calling this method, it must be called before calling // InitSslServer. // bool AddSslAcceptableClientCaDn(const wchar_t *certAuthDN); // 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 method. // // Note:This method will find a random unused port to listen on if you bind to port // 0. The chosen port is available via the read-only ListenPort property after this // method returns successful. // // To bind and listen using IPv6, set the ListenIpv6 property = true prior to // calling this method. // // What is a reasonable value for backLog? The answer depends on how many simultaneous // incoming connections could be expected, and how quickly your application can // process an incoming connection and then return to accept the next connection. // bool BindAndListen(int port, int backLog); // Creates an asynchronous task to call the BindAndListen method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *BindAndListenAsync(int port, int backLog); // Binds a TCP socket to an unused port within a port range (beginPort to endPort) 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 method. // // To bind and listen using IPv6, set the ListenIpv6 property = true prior to // calling this method. // // Returns the port number that was bound, or -1 if no port was available or if it // failed for some other reason. // int BindAndListenPortRange(int beginPort, int endPort, int backLog); // Creates an asynchronous task to call the BindAndListenPortRange method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *BindAndListenPortRangeAsync(int beginPort, int endPort, int backLog); // Convenience method for building a simple HTTP GET request from a URL. bool BuildHttpGetRequest(const wchar_t *url, CkString &outStr); // Convenience method for building a simple HTTP GET request from a URL. const wchar_t *buildHttpGetRequest(const wchar_t *url); // 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. // // A maxWaitMs value of 0 indicates a poll. // int CheckWriteable(int maxWaitMs); // Creates an asynchronous task to call the CheckWriteable method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *CheckWriteableAsync(int maxWaitMs); // Clears the contents of the SessionLog property. void ClearSessionLog(void); // Applications should instead call DupSocket . // // Creates a copy that shares the same underlying TCP (or SSL/TLS) connection. This // allows for simultaneous reading/writing by different threads on the socket. When // using asynchronous reading/writing, it is not necessary to clone the socket. // However, if separate background threads are making synchronous calls to // read/write, then one thread may use the original socket, and the other should // use a clone. // // The caller is responsible for deleting the object returned by this method. CkSocketW *CloneSocket(void); // Cleanly terminates and closes a TCP, TLS, or SSH channel connection. bool Close(int maxWaitMs); // Creates an asynchronous task to call the Close method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *CloseAsync(int maxWaitMs); // Establishes a secure SSL/TLS or a plain non-secure TCP connection with a remote // host:port. This is a blocking call. The maximum wait time (in milliseconds) is // passed in maxWaitMs. This is the amount of time the app is willing to wait for the // TCP connection to be accepted (see additional notes below). // // The hostname can be a domain name (i.e. example.com), an IPv4 dotted address string // such as 3.101.18.47 , or an IPv6 address string such as // 2345:0425:2CA1:0000:0000:0567:5673:23b5 , or 2345:0425:2CA1::0567:5673:23b5 , // etc. // // To establish an SSL/TLS connection, set ssl = true, otherwise set ssl = // false for a normal TCP connection. Note: The timeouts that apply to the // internal SSL/TLS handshaking messages are the MaxReadIdleMs and MaxSendIdleMs // properties. // // Note: The maxWaitMs only applies to the actual TCP connect, i.e. the max time to wait // for the TCP connect to be accepted. The MaxReadIdleMs property applies to DNS // (if hostname is a domain name), to any SOCKS or HTTP proxy communications, and to // SSL/TLS handshake communications. // // Note: Connections do not automatically close because of inactivity. A connection // will remain open indefinitely even if there is no activity. // // Important: All TCP-based Internet communications, regardless of the protocol // (such as HTTP, FTP, SSH, IMAP, POP3, SMTP, etc.), and regardless of SSL/TLS, // begin with establishing a TCP connection to a remote host:port. External // security-related infrastructure such as software firewalls (Windows Firewall), // hardware firewalls, anti-virus, at either source or destination (or both) can // block the connection. If the connection fails, make sure to check all potential // external causes of blockage. // // Question: How do I Choose the TLS version, such as 1.2? Answer: The client does // not specifically choose the TLS version. In the TLS handshake (which is what // occurs internally in this method), the client tells the server the version of // the TLS protocol it wishes to use, which should be the highest version is // supports. In this case, (at the time of this writing on 22-June-2017) it is TLS // 1.2. The server then chooses the TLS version that will actually be used. In most // cases it will be TLS 1.2. The client can then choose to accept or reject the // connection based on the TLS version chosen by the server. By default, Chilkat // will reject anything lower than SSL 3.0 (i.e. SSL 2.0 or lower is rejected). The // SslProtocol property can be set to change what is accepted by Chilkat. For // example, it can be set to TLS 1.0 or higher . // bool Connect(const wchar_t *hostname, int port, bool ssl, int maxWaitMs); // Creates an asynchronous task to call the Connect method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ConnectAsync(const wchar_t *hostname, int port, bool ssl, int maxWaitMs); // Closes the secure (TLS/SSL) channel leaving the socket in a connected state // where data sent and received is unencrypted. bool ConvertFromSsl(void); // Creates an asynchronous task to call the ConvertFromSsl method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ConvertFromSslAsync(void); // Converts a non-SSL/TLS connected socket to a secure channel using TLS/SSL. bool ConvertToSsl(void); // Creates an asynchronous task to call the ConvertToSsl method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ConvertToSslAsync(void); // This function clears the Chilkat in-memory DNS cache, which stores // hostname-to-IP address mappings to avoid repeated DNS lookups. // // Note: // // * The DNS cache is shared across all Chilkat objects, so clearing it will // impact all such objects. // * Chilkat's DNS caching respects the TTL (time to live) of DNS records. If // the TTL has expired since the initial lookup, Chilkat will perform a new DNS // query and update the cache with the latest IP address. void DnsCacheClear(void); // 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. bool DnsLookup(const wchar_t *hostname, int maxWaitMs, CkString &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. const wchar_t *dnsLookup(const wchar_t *hostname, int maxWaitMs); // Creates an asynchronous task to call the DnsLookup method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *DnsLookupAsync(const wchar_t *hostname, int maxWaitMs); // Creates a copy in dest that uses the same underlying TCP or SSL/TLS connection // as the caller, enabling simultaneous reading and writing by different threads on // the socket. bool DupSocket(CkSocketW &dest); // Retrieves network adapter information, including IP addresses (IPv4 and IPv6) // and MAC addresses. The information is returned in json. See the example below. bool GetAdaptersAddresses(CkJsonObjectW &json); // Provides information about what transpired in the last method called on this // object instance. For many methods, there is no information. However, for some // methods, details about what occurred can be obtained by getting the LastJsonData // right after the method call returns. void GetLastJsonData(CkJsonObjectW &json); // Applications should instead call GetMyServerCert . // // 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. // // The caller is responsible for deleting the object returned by this method. CkCertW *GetMyCert(void); // Returns in cert the digital certificate for TLS connections. This method is // intended for use by a TLS server application and requires prior specification of // the TLS certificate via the InitSslServer call. bool GetMyServerCert(CkCertW &cert); // This method retrieves the Nth client certificate received during an SSL/TLS // handshake on the server side of the connection. The first client certificate is // found at index 0. The number of certificates received is available in the // NumReceivedClientCerts property. The client certificate is returned in cert. // // Client certificates are typically sent only when the server requests client-side // authentication, such as in a two-way SSL/TLS connection. (2-way TLS (also known // as mutual TLS or mTLS) is a form of Transport Layer Security (TLS) in which both // the client and the server authenticate each other using digital certificates.) // // This method enables the server to access and examine client certificates // immediately after the connection is established. If the client certificates do // not meet authentication requirements, the server may disconnect. // // Important: Call this method on the socket object returned by // AcceptNextConnection . // bool GetRcvdClientCert(int index, CkCertW &cert); // Applications should instead call GetRcvdClientCert . // // Returns the Nth client certificate received during an SSL/TLS handshake. This // method only applies to the server-side of an SSL/TLS connection. The 1st client // certificate is at index 0. The NumReceivedClientCerts property indicates the // number of client certificates received during the SSL/TLS connection // establishment. // // Client certificates are customarily only sent when the server demands // client-side authentication, as in 2-way SSL/TLS. This method provides the // ability for the server to access and examine the client-side certs immediately // after a connection is established. (Of course, if the client-side certs are // inadequate for authentication, then the application can choose to immediately // disconnect.) // // Important: This method should be called from the socket object that is returned // by AcceptNextConnection. // // The caller is responsible for deleting the object returned by this method. CkCertW *GetReceivedClientCert(int index); // This method returns the digital certificate of the remote SSL server for the // current SSL connection on the client side. The certificate is returned in cert. // If the socket is not connected or is not using SSL, it returns false. bool GetServerCert(CkCertW &cert); // If connected as an SSL/TLS client to an SSL/TLS server where the server requires // a client-side certificate for authentication, then the NumSslAcceptableClientCAs // property contains the number of acceptable certificate authorities sent by the // server during connection establishment handshake. This method may be called to // get the Distinguished Name (DN) of each acceptable CA. The index should range // from 0 to NumSslAcceptableClientCAs - 1. bool GetSslAcceptableClientCaDn(int index, CkString &outStr); // If connected as an SSL/TLS client to an SSL/TLS server where the server requires // a client-side certificate for authentication, then the NumSslAcceptableClientCAs // property contains the number of acceptable certificate authorities sent by the // server during connection establishment handshake. This method may be called to // get the Distinguished Name (DN) of each acceptable CA. The index should range // from 0 to NumSslAcceptableClientCAs - 1. const wchar_t *getSslAcceptableClientCaDn(int index); // If connected as an SSL/TLS client to an SSL/TLS server where the server requires // a client-side certificate for authentication, then the NumSslAcceptableClientCAs // property contains the number of acceptable certificate authorities sent by the // server during connection establishment handshake. This method may be called to // get the Distinguished Name (DN) of each acceptable CA. The index should range // from 0 to NumSslAcceptableClientCAs - 1. const wchar_t *sslAcceptableClientCaDn(int index); // This method returns the digital certificate of the remote SSL server for the // current SSL connection on the client side. If the socket is not connected or is // not using SSL, it returns a NULL reference. // The caller is responsible for deleting the object returned by this method. CkCertW *GetSslServerCert(void); // SSL/TLS Server applications should call this method with the SSL server // certificate to be used for SSL/TLS connections. It should be called prior to // accepting connections. This method has an intended side-effect: If not already // connected, then the Ssl property is set to true. // bool InitSslServer(CkCertW &cert); // This method is deprecated. Call GetLastJsonData instead. // // Provides information about what transpired in the last method called on this // object instance. For many methods, there is no information. However, for some // methods, details about what occurred can be obtained by getting the LastJsonData // right after the method call returns. // // The caller is responsible for deleting the object returned by this method. CkJsonObjectW *LastJsonData(void); // Loads the caller of the task's async method. bool LoadTaskCaller(CkTaskW &task); // Loads the socket object from a completed asynchronous task. bool LoadTaskResult(CkTaskW &task); // 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 PollDataAvailable(void); // Creates an asynchronous task to call the PollDataAvailable method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *PollDataAvailableAsync(void); // Receives as much data as is immediately available on a connected TCP socket and // appends the incoming data to binData. If no data is immediately available, it waits // up to MaxReadIdleMs milliseconds for data to arrive. bool ReceiveBd(CkBinDataW &binData); // Creates an asynchronous task to call the ReceiveBd method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveBdAsync(CkBinDataW &binData); // Reads exactly numBytes bytes from the connection. This method blocks until numBytes // bytes are read or the read times out. The timeout is specified by the // MaxReadIdleMs property (in milliseconds). bool ReceiveBdN(unsigned long numBytes, CkBinDataW &binData); // Creates an asynchronous task to call the ReceiveBdN method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveBdNAsync(unsigned long numBytes, CkBinDataW &binData); // Receives a single byte. The received byte will be available in the ReceivedInt // property. If bUnsigned is true, then a value from 0 to 255 is returned in // ReceivedInt. If bUnsigned is false, then a value from -128 to +127 is returned. bool ReceiveByte(bool bUnsigned); // Creates an asynchronous task to call the ReceiveByte method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveByteAsync(bool bUnsigned); // 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 ReceiveBytes(CkByteData &outData); // Creates an asynchronous task to call the ReceiveBytes method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveBytesAsync(void); // The same as ReceiveBytes, except the bytes are returned in encoded string form // according to encodingAlg. The encodingAlg can be Base64 , modBase64 , Base32 , UU , QP (for // quoted-printable), URL (for url-encoding), Hex , Q , B , url_oath , url_rfc1738 // , url_rfc2396 , or url_rfc3986 . bool ReceiveBytesENC(const wchar_t *encodingAlg, CkString &outStr); // The same as ReceiveBytes, except the bytes are returned in encoded string form // according to encodingAlg. The encodingAlg can be Base64 , modBase64 , Base32 , UU , QP (for // quoted-printable), URL (for url-encoding), Hex , Q , B , url_oath , url_rfc1738 // , url_rfc2396 , or url_rfc3986 . const wchar_t *receiveBytesENC(const wchar_t *encodingAlg); // Creates an asynchronous task to call the ReceiveBytesENC method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveBytesENCAsync(const wchar_t *encodingAlg); // 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 ReceiveBytesN(unsigned long numBytes, CkByteData &outData); // Creates an asynchronous task to call the ReceiveBytesN method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveBytesNAsync(unsigned long numBytes); // 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. // bool ReceiveBytesToFile(const wchar_t *appendFilename); // Creates an asynchronous task to call the ReceiveBytesToFile method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveBytesToFileAsync(const wchar_t *appendFilename); // Receives a 4-byte signed integer and returns the value received. Returns -1 on // error. int ReceiveCount(void); // Creates an asynchronous task to call the ReceiveCount method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveCountAsync(void); // Receives a 16-bit integer (2 bytes). The received integer will be available in // the ReceivedInt property. Set bigEndian equal to true if the incoming 16-bit // integer is in big-endian byte order. Otherwise set bigEndian equal to false for // receving a little-endian integer. If bUnsigned is true, the ReceivedInt will range // from 0 to 65,535. If bUnsigned is false, the ReceivedInt will range from -32,768 // through 32,767. bool ReceiveInt16(bool bigEndian, bool bUnsigned); // Creates an asynchronous task to call the ReceiveInt16 method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveInt16Async(bool bigEndian, bool bUnsigned); // Receives a 32-bit integer (4 bytes). The received integer will be available in // the ReceivedInt property. Set bigEndian equal to true if the incoming 32-bit // integer is in big-endian byte order. Otherwise set bigEndian equal to false for // receving a little-endian integer. bool ReceiveInt32(bool bigEndian); // Creates an asynchronous task to call the ReceiveInt32 method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveInt32Async(bool bigEndian); // The same as ReceiveBytesN, except the bytes are returned in encoded string form // using the encoding specified by numBytes. The numBytes can be Base64 , modBase64 , // Base32 , UU , QP (for quoted-printable), URL (for url-encoding), Hex , Q , B , // url_oath , url_rfc1738 , url_rfc2396 , or url_rfc3986 . bool ReceiveNBytesENC(unsigned long numBytes, const wchar_t *encodingAlg, CkString &outStr); // The same as ReceiveBytesN, except the bytes are returned in encoded string form // using the encoding specified by numBytes. The numBytes can be Base64 , modBase64 , // Base32 , UU , QP (for quoted-printable), URL (for url-encoding), Hex , Q , B , // url_oath , url_rfc1738 , url_rfc2396 , or url_rfc3986 . const wchar_t *receiveNBytesENC(unsigned long numBytes, const wchar_t *encodingAlg); // Creates an asynchronous task to call the ReceiveNBytesENC method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveNBytesENCAsync(unsigned long numBytes, const wchar_t *encodingAlg); // Receives as much data as is immediately available on the connection. 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 appended to sb. bool ReceiveSb(CkStringBuilderW &sb); // Creates an asynchronous task to call the ReceiveSb method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveSbAsync(CkStringBuilderW &sb); // 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 ReceiveString(CkString &outStr); // 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 wchar_t *receiveString(void); // Creates an asynchronous task to call the ReceiveString method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveStringAsync(void); // 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 ReceiveStringMaxN(int maxByteCount, CkString &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.) // const wchar_t *receiveStringMaxN(int maxByteCount); // Creates an asynchronous task to call the ReceiveStringMaxN method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveStringMaxNAsync(int maxByteCount); // 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 ReceiveStringUntilByte(int lookForByte, CkString &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. const wchar_t *receiveStringUntilByte(int lookForByte); // Creates an asynchronous task to call the ReceiveStringUntilByte method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveStringUntilByteAsync(int lookForByte); // 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 ReceiveToCRLF(CkString &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. const wchar_t *receiveToCRLF(void); // Creates an asynchronous task to call the ReceiveToCRLF method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveToCRLFAsync(void); // 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 ReceiveUntilByte(int lookForByte, CkByteData &outBytes); // Creates an asynchronous task to call the ReceiveUntilByte method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveUntilByteAsync(int lookForByte); // 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. The received bytes are // appended to bd. bool ReceiveUntilByteBd(int lookForByte, CkBinDataW &bd); // Creates an asynchronous task to call the ReceiveUntilByteBd method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveUntilByteBdAsync(int lookForByte, CkBinDataW &bd); // 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. // // Remember: All Receive* methods will stop trying to receive if incoming data // stops arriving for more than the number of milliseconds indicated by the // MaxReadIdleMs property. If this happens, the method return value indicates // failure and the ReceiveFailReason property would have the value 5 (for Timeout). // bool ReceiveUntilMatch(const wchar_t *matchStr, CkString &outStr); // 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. // // Remember: All Receive* methods will stop trying to receive if incoming data // stops arriving for more than the number of milliseconds indicated by the // MaxReadIdleMs property. If this happens, the method return value indicates // failure and the ReceiveFailReason property would have the value 5 (for Timeout). // const wchar_t *receiveUntilMatch(const wchar_t *matchStr); // Creates an asynchronous task to call the ReceiveUntilMatch method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveUntilMatchAsync(const wchar_t *matchStr); // The same as ReceiveUntilMatch, but returns the received string appended to the // contents of sb. bool ReceiveUntilMatchSb(const wchar_t *matchStr, CkStringBuilderW &sb); // Creates an asynchronous task to call the ReceiveUntilMatchSb method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *ReceiveUntilMatchSbAsync(const wchar_t *matchStr, CkStringBuilderW &sb); // Resets the performance measurements for either receiving or sending. If rcvPerf is // true, then the receive performance monitoring is reset. If rcvPerf is false, // then the sending performance monitoring is reset. void ResetPerf(bool rcvPerf); // Wait for data to arrive on this socket, or any of the contained sockets if the // caller is a socket set . (If the socket is a listener socket, then waits for an // incoming connect. Listener sockets can be added to the socket set just like // connected sockets.) // // (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 SelectForReading(int timeoutMs); // Creates an asynchronous task to call the SelectForReading method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SelectForReadingAsync(int timeoutMs); // Waits until it is known that data can be written to one or more sockets without // it blocking. // // Socket writes are typically buffered by the operating system. When an // application writes data to a socket, the operating system appends it to the // socket's outgoing send buffers and returns immediately. However, if the OS send // buffers become filled up (because the sender is sending data faster than the // remote receiver can read it), then a socket write can block (until outgoing send // buffer space becomes available). // // Waits a maximum of timeoutMs milliseconds. If maxWaitMs = 0, then it is effectively a // poll. Returns the number of sockets such that data can be written without // blocking. A value of -1 indicates an error condition. // int SelectForWriting(int timeoutMs); // Creates an asynchronous task to call the SelectForWriting method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SelectForWritingAsync(int timeoutMs); // Sends bytes from binData 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. // // Set offset and/or numBytes to non-zero values to send a portion of the binData. If offset // and numBytes are both 0, then the entire binData is sent. If offset is non-zero and numBytes // is zero, then the bytes starting at offset until the end are sent. // bool SendBd(CkBinDataW &binData, unsigned long offset, unsigned long numBytes); // Creates an asynchronous task to call the SendBd method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SendBdAsync(CkBinDataW &binData, unsigned long offset, unsigned long numBytes); // Sends a single byte. The integer must have a value from 0 to 255. bool SendByte(int value); // Creates an asynchronous task to call the SendByte method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SendByteAsync(int value); // 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. bool SendBytes(CkByteData &data); // Creates an asynchronous task to call the SendBytes method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SendBytesAsync(CkByteData &data); // Sames as SendBytes but data is passed via a pointer and length. bool SendBytes2(const void *pByteData, unsigned long szByteData); // The same as SendBytes, except the bytes are provided in encoded string form as // specified by encodingAlg. The encodingAlg can be Base64 , modBase64 , Base32 , Base58 , UU , // QP (for quoted-printable), URL (for url-encoding), Hex , Q , B , url_oauth , // url_rfc1738 , url_rfc2396 , and url_rfc3986 . // // For example, you can call this method with the following arguments: // 00010203040506 , hex to send 7 binary bytes with values 00, 01, 02, 03, 04, 05, // 06. // bool SendBytesENC(const wchar_t *encodedBytes, const wchar_t *encodingAlg); // Creates an asynchronous task to call the SendBytesENC method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SendBytesENCAsync(const wchar_t *encodedBytes, const wchar_t *encodingAlg); // 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. bool SendCount(int byteCount); // Creates an asynchronous task to call the SendCount method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SendCountAsync(int byteCount); // Sends a 16-bit integer (2 bytes). Set bigEndian equal to true to send the integer // in big-endian byte order (this is the standard network byte order). Otherwise // set bigEndian equal to false to send in little-endian byte order. bool SendInt16(int value, bool bigEndian); // Creates an asynchronous task to call the SendInt16 method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SendInt16Async(int value, bool bigEndian); // Sends a 32-bit integer (4 bytes). Set bigEndian equal to true to send the integer // in big-endian byte order (this is the standard network byte order). Otherwise // set bigEndian equal to false to send in little-endian byte order. bool SendInt32(int value, bool bigEndian); // Creates an asynchronous task to call the SendInt32 method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SendInt32Async(int value, bool bigEndian); // Sends the contents of sb over the connection. 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. // bool SendSb(CkStringBuilderW &sb); // Creates an asynchronous task to call the SendSb method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SendSbAsync(CkStringBuilderW &sb); // 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. // bool SendString(const wchar_t *stringToSend); // Creates an asynchronous task to call the SendString method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SendStringAsync(const wchar_t *stringToSend); // Sends a Wake on Lan magic packet to a computer. A Wake on Lan is a way to power // on a computer remotely by sending a data packet known as a magic packet. For // this to work, the network card must have enabled the feature: “Power on Lan” or // “Power on PCI Device“, which is done by accessing the BIOS of the machine. // // The macAddress is the MAC address (in hex) of the computer to wake. A MAC address // should be 6 bytes in length. For example, 000102030405 . The port is the port // which should be 7 or 9. (Port number 9 is more commonly used.) The ipBroadcastAddr is the // broadcast address of your network, which usually ends with *.255. For example: // 192.168.1.255 . // // Your application does not call Connect prior to calling SendWakeOnLan. To use // this method, it's just a matter of instantiating an instance of this socket // object and then call SendWakeOnLan. // bool SendWakeOnLan(const wchar_t *macAddress, int port, const wchar_t *ipBroadcastAddr); // The same as SendWakeOnLan, but includes an additional argument to specify a // SecureOn password. The password should be a hexidecimal string representing 4 or 6 // bytes. (See https://wiki.wireshark.org/WakeOnLAN) Sending a WakeOnLAN (WOL) to // an IPv4 address would need a 4-byte SecureOn password, whereas an IPv6 address // would need a 6-byte SecureOn password. bool SendWakeOnLan2(const wchar_t *macAddress, int port, const wchar_t *ipBroadcastAddr, const wchar_t *password); // 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 SetSslClientCert(CkCertW &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 PEM file. bool SetSslClientCertPem(const wchar_t *pemDataOrFilename, const wchar_t *pemPassword); // 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. bool SetSslClientCertPfx(const wchar_t *pfxFilename, const wchar_t *pfxPassword); // Convenience method to force the calling thread to sleep for a number of // milliseconds. void SleepMs(int millisec); // Authenticates with the SSH server using public-key authentication. The // corresponding public key must have been installed on the SSH server for the // sshLogin. Authentication will succeed if the matching privateKey is provided. // // Important: When reporting problems, please send the full contents of the // LastErrorText property to support@chilkatsoft.com. // bool SshAuthenticatePk(const wchar_t *sshLogin, CkSshKeyW &privateKey); // Creates an asynchronous task to call the SshAuthenticatePk method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SshAuthenticatePkAsync(const wchar_t *sshLogin, CkSshKeyW &privateKey); // Authenticates with the SSH server using a sshLogin and sshPassword. This method is only // used for SSH tunneling. The tunnel is established by calling SshOpenTunnel, then // (if necessary) authenticated by calling SshAuthenticatePw or SshAuthenticatePk. bool SshAuthenticatePw(const wchar_t *sshLogin, const wchar_t *sshPassword); // Creates an asynchronous task to call the SshAuthenticatePw method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SshAuthenticatePwAsync(const wchar_t *sshLogin, const wchar_t *sshPassword); // Closes the SSH tunnel previously opened by SshOpenTunnel. bool SshCloseTunnel(void); // Creates an asynchronous task to call the SshCloseTunnel method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SshCloseTunnelAsync(void); // Opens a new channel within an SSH tunnel and provides the socket connected to // the specified destination host:port through SSH port forwarding in channel. If ssl // is true, the connection uses TLS within the SSH tunnel. Multiple channels can // be opened within one SSH tunnel, each possibly forwarding to different remote // host:port endpoints. bool SshNewChannel(const wchar_t *hostname, int port, bool ssl, int maxWaitMs, CkSocketW &channel); // Creates an asynchronous task to call the SshNewChannel method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SshNewChannelAsync(const wchar_t *hostname, int port, bool ssl, int maxWaitMs, CkSocketW &channel); // Applications should instead call SshNewChannel . // // Opens a new channel within an SSH tunnel. Returns the socket that is connected // to the destination host:port through the SSH tunnel via port forwarding. If ssl // is true, the connection is TLS (i.e. TLS inside the SSH tunnel). Returns the // socket object that is the port-forwarded tunneled connection. Any number of // channels may be opened within a single SSH tunnel, and may be port-forwarded to // different remote host:port endpoints. // // The caller is responsible for deleting the object returned by this method. CkSocketW *SshOpenChannel(const wchar_t *hostname, int port, bool ssl, int maxWaitMs); // Creates an asynchronous task to call the SshOpenChannel method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SshOpenChannelAsync(const wchar_t *hostname, int port, bool ssl, int maxWaitMs); // Connects to an SSH server and creates a tunnel for port forwarding. The sshHostname is // the hostname (or IP address) of the SSH server. The sshPort is typically 22, which // is the standard SSH port number. // // An SSH tunneling (port forwarding) session always begins by first calling // SshOpenTunnel to connect to the SSH server, followed by calling either // SshAuthenticatePw or SshAuthenticatePk to authenticate. A program would then // call SshOpenChannel to connect to the destination server (via the SSH tunnel). // Any number of channels can be opened over the same SSH tunnel. // // The MaxReadIdleMs property applies to this method for controlling how long it // takes before a timeout. // bool SshOpenTunnel(const wchar_t *sshHostname, int sshPort); // Creates an asynchronous task to call the SshOpenTunnel method with the arguments // provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *SshOpenTunnelAsync(const wchar_t *sshHostname, int sshPort); // Used in combination with the ElapsedSeconds property, which will contain the // number of seconds since the last call to this method. (The StartTiming method // and ElapsedSeconds property is provided for convenience.) void StartTiming(void); // Takes the connection from sock. If the caller of this method had an open // connection, then it will be closed. This method is different than the TakeSocket // method because the caller does not become a socket set . bool TakeConnection(CkSocketW &sock); // Takes ownership of the sock. sock is added to the internal set of connected // sockets. The caller object is now effectively a socket set , i.e. a collection // of connected and/or listener 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 link below. bool TakeSocket(CkSocketW &sock); // Initiates a renegotiation of the TLS security parameters. This sends a // ClientHello to re-do the TLS handshake to establish new TLS security params. bool TlsRenegotiate(void); // Creates an asynchronous task to call the TlsRenegotiate method with the // arguments provided. // The caller is responsible for deleting the object returned by this method. CkTaskW *TlsRenegotiateAsync(void); // Uses an existing SSH tunnel for the connection. This is an alternative way of // establishing a socket connection through an SSH tunnel. There are four ways of // running a TCP or SSL/TLS connection through an SSH tunnel: // 1. UseSsh // 1. Establish the SSH connection and authenticate using the Chilkat SSH // object. // 2. Call UseSsh to indicate that the connections should be made through // the SSH tunnel. // 3. Call the Connect method to establish the TCP or SSL/TLS connection // with a destination host:port. The connection is not direct, but will instead be // routed through the SSH tunnel and then port-forwarded (from the SSH server) to // the destination host:port. (Had UseSsh not been called, the connection would be // direct.) // SshOpenTunnel // 1. Call the Socket object's SshOpenTunnel method to connect to an SSH // server. // 2. Call SshAuthenticatePw to authenticate with the SSH server. // 3. Instead of calling Connect to connect with the destination host:port, // the SshOpenChannel method is called to connect via port-forwarding through the // SSH tunnel. // SshTunnel object with dynamic port forwarding // 1. The Chilkat SSH Tunnel object is utilized to run in a background // thread. It connects and authenticates with an SSH server, and then listens at a // port chosen by the application, and behaves as a SOCKS5 proxy server. // 2. The Socket object sets the SOCKS5 proxy host:port to // localhost:_LT_port_GT_, // 3. The Socket's Connect method is called to connect via the SSH Tunnel. // The connection is routed through the SSH tunnel via dynamic port forwarding. // 4. Once the background SSH Tunnel thread is running, it can handle any // number of incoming connections from the foreground thread, other threads, or // even other programs that are local or remote. Each incoming connection is routed // via dynamic port forwarding to it's chosen destnation host:port on it's own // logical SSH channel. // SshTunnel object with hard-coded port forwarding // 1. The Chilkat SSH Tunnel object is utilized to run in a background // thread. It connects and authenticates with an SSH server, and then listens at a // port chosen by the application. It does not behave as a SOCKS5 proxy server, but // instead has a hard-coded destination host:port. // 2. The Socket's Connect method is called to connect to // localhost:_LT_port_GT_. The connection is automatically port-forwarded through // the SSH tunnel to the hard-coded destination host:port. // In all cases, the SSH tunnels can hold both unencrypted TCP connections and // SSL/TLS connections. bool UseSsh(CkSshW &ssh); // END PUBLIC INTERFACE }; #if !defined(__sun__) && !defined(__sun) #pragma pack (pop) #endif #endif