CkSocket Perl Programming
Reference Documentation
CkSocket
TCP socket component with SSL capability. Supports both asynchronous connect, accept, send, and read operations in all programming languages. The ActiveX and .NET socket components also include heartbeat, completion, and other events when blocking methods are called. DNS and reverse DNS is support in both synchronous and asynchronous modes. Supports the ability to abort all operations: connect, accept, send, receive, DNS lookups, etc. prior to completion.
Object Creation
$obj = new chilkat::CkSocket();
Properties
# Returns a boolean value
get_AsyncAcceptFinished( )
Set to 1 when an asynchronous accept operation completes. Once the asynchronous accept has finished, the success/failure is available in the AsyncAcceptSuccess boolean property.
# str is a CkString object (output)
get_AsyncAcceptLog( str )
Contains the last-error information for an asynchronous accept operation.
# Returns a boolean value
get_AsyncAcceptSuccess( )
Set to 1 when an asynchronous accept operation completes and is successful.
# Returns a boolean value
get_AsyncConnectFinished( )
Set to 1 when an asynchronous connect operation completes.
Once the asynchronous connect has finished, the success/failure is available in the AsyncConnectSuccess boolean property.
# str is a CkString object (output)
get_AsyncConnectLog( str )
Contains the last-error information for an asynchronous connect operation.
# Returns a boolean value
get_AsyncConnectSuccess( )
Set to 1 when an asynchronous connect operation completes and is successful.
# Returns a boolean value
get_AsyncDnsFinished( )
Set to 1 when an asynchronous DNS query completes. The success status is available in the AsyncDnsSuccess property.
# str is a CkString object (output)
get_AsyncDnsLog( str )
Contains the last-error information for an asynchronous DNS query.
# str is a CkString object (output)
get_AsyncDnsResult( str )
The IP address of the last asynchronous DNS query completed. The IP address is in nnn.nnn.nnn.nnn string form.
# Returns a boolean value
get_AsyncDnsSuccess( )
Set to 1 when an asynchronous DNS query completes and is successful.
# Returns a boolean value
get_AsyncReceiveFinished( )
Set to 1 when an asynchronous receive operation completes. Once the asynchronous receive has finished, the success/failure is available in the AsyncReceiveSuccess boolean property.
# str is a CkString object (output)
get_AsyncReceiveLog( str )
Contains the last-error information for an asynchronous receive operation.
# Returns a boolean value
get_AsyncReceiveSuccess( )
Set to 1 when an asynchronous receive operation completes and is successful.
# byteData is a CkByteData object (output)
get_AsyncReceivedBytes( byteData )
Contains the data received in an asynchronous receive operation (when receiving bytes asynchronously).
# str is a CkString object (output)
get_AsyncReceivedString( str )
Contains the string received in an asynchronous receive operation (when receiving a string asynchronously).
# Returns a boolean value
get_AsyncSendFinished( )
Set to 1 when an asynchronous send operation completes. Once the asynchronous send has finished, the success/failure is available in the AsyncSendSuccess boolean property.
# str is a CkString object (output)
get_AsyncSendLog( str )
Contains the last-error information for an asynchronous send operation.
# Returns a boolean value
get_AsyncSendSuccess( )
Set to 1 when an asynchronous send operation completes and is successful.
# str is a CkString object (output)
get_ClientIpAddress( str )
# newVal is a string (input)
put_ClientIpAddress( newVal )
(PreRelease) 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".
# Returns an integer value
get_ConnectFailReason( )
If the Connect method fails, this property can be checked to determine the reason for failure.
Possible values are:
0 = success
Normal (non-SSL) sockets:
1 = empty hostname
2 = DNS lookup failed
3 = DNS timeout
4 = Aborted by application.
5 = Internal failure.
6 = Connect Timed Out
7 = Connect Rejected (or failed for some other reason)
SSL:
100 = Internal schannel error
101 = Failed to create credentials
102 = Failed to send initial message to proxy.
103 = Handshake failed.
104 = Failed to obtain remote certificate.
# Returns an integer value
get_DebugConnectDelayMs( )
# millisec is an integer (input)
put_DebugConnectDelayMs( millisec )
Used to simulate a long wait when connecting to a remote server. If your application wishes to test for the handling of timeouts, you may set this value to a number of milliseconds greater than max-wait specified in the Connect method call. The default value is 0.
# Returns an integer value
get_DebugDnsDelayMs( )
# millisec is an integer (input)
put_DebugDnsDelayMs( millisec )
Used to simulate a long wait when doing a DNS lookup. If your application wishes to test for the handling of timeouts, you may set this value to a number of milliseconds greater than max-wait specified in the DnsLookup method call. The default value is 0.
# Returns an integer value
get_HeartbeatMs( )
# millisec is an integer (input)
put_HeartbeatMs( millisec )
The number of milliseconds between periodic heartbeat callbacks for blocking socket operations (connect, accept, dns query, send, receive). Set this to 0 to disable heartbeat events. The default value is 1000 (i.e. 1 heartbeat callback per second).
# Returns a boolean value
get_IsConnected( )
Returns 1 if the socket is connected. Otherwise returns 0.
# Returns a boolean value
get_KeepSessionLog( )
# newVal is a boolean (input)
put_KeepSessionLog( newVal )
Controls whether socket (or SSL) communications are logged to the SessionLog string property. To turn on session logging, set this property = 1, otherwise set to 0 (which is the default value).
# str is a CkString object (output)
LastErrorHtml( str )
To be documented soon.Error information in HTML format for the last method called.
# str is a CkString object (output)
LastErrorText( str )
Error information in plain-text format for the last method called.
# str is a CkString object (output)
LastErrorXml( str )
To be documented soon.Error information in XML format for the last method called.
# Returns a boolean value
get_LastMethodFailed( )
1 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.
# Returns an integer value
get_MaxReadIdleMs( )
# millisec is an integer (input)
put_MaxReadIdleMs( millisec )
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.
# Returns an integer value
get_MaxSendIdleMs( )
# millisec is an integer (input)
put_MaxSendIdleMs( millisec )
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.
# str is a CkString object (output)
get_MyIpAddress( str )
Returns the local IP address of the socket. 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.".
# Returns an integer value
get_ObjectId( )
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.
# Returns an integer value
get_ReceivePacketSize( )
# sizeInBytes is an integer (input)
put_ReceivePacketSize( sizeInBytes )
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.
# str is a CkString object (output)
get_RemoteIpAddress( str )
When a socket is connected, the remote IP address of the connected peer is available in this property.
# Returns an integer value
get_RemotePort( )
When a socket is connected, the remote port of the connected peer is available in this property.
# Returns an integer value
get_SendPacketSize( )
# sizeInBytes is an integer (input)
put_SendPacketSize( sizeInBytes )
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 4096.
# str is a CkString object (output)
get_SessionLog( str )
Contains a log of the bytes sent and received on this socket. The KeepSessionLog property must be set to 1 for logging to occur.
# str is a CkString object (output)
get_SessionLogEncoding( str )
# newVal is a string (input)
put_SessionLogEncoding( newVal )
Controls how the data is encoded in the SessionLog. Possible values are "esc" and "hex". The default value is "esc".
When set to "hex", the bytes are encoded as a hexidecimalized string.
The "esc" encoding is a C-string like encoding, and is more compact than hex if most of the data to be logged is text. Printable us-ascii chars are unmodified. Common "C" control chars are represented as "\r", "\n", "\t", etc. Non-printable and byte values greater than 0x80 are escaped using a backslash and hex encoding: \xHH. Certain printable chars are backslashed: SPACE, double-quote, single-quote, etc.
# Returns a boolean value
get_Ssl( )
# newVal is a boolean (input)
put_Ssl( newVal )
Set this property to 1 if the socket requires an SSL connection. The default value is 0.
# str is a CkString object (output)
get_SslProtocol( str )
# newVal is a string (input)
put_SslProtocol( newVal )
Selects the secure protocol to be used for secure (SSL) connections. Possible values are:
default
TLS 1.0
SSL 3.0
SSL 2.0
PCT 1.0
The default value is "default", which allows for the protocol to be selected dynamically at runtime based on the requirements of the server.
# str is a CkString object (output)
get_StringCharset( str )
# str is a string (input)
put_StringCharset( 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".
# Returns a boolean value
get_Utf8( )
# b is a boolean (input)
put_Utf8( b )
When set to true, all "const char *" arguments are expected to be utf-8 strings. If set to false, the "const char *" arguments are expected to be ANSI strings.
# str is a CkString object (output)
get_Version( str )
The version of this component, such as "v1.0.0"
Methods
# maxWaitMs is an integer (input)
AcceptNextConnection( maxWaitMs )
Blocking call to accept the next incoming connection on the socket. maxWaitMs specifies the maximum time to wait (in milliseconds). Set this to 0 to wait indefinitely. If successful, a new socket object is returned.
AsyncAcceptAbort( )
Call this to abort an asynchronous socket connect that is running in a background thread. Asynchronous connects are initiated by calling AsyncAcceptStart.
AsyncAcceptSocket( )
Returns the socket object for the connection accepted asynchronously in a background thread (via AsyncAcceptStart). The connected socket can only be retrieved once. A subsequent call to AsyncAcceptSocket will return a NULL reference until another connection is accepted asynchronously.
# maxWaitMs is an integer (input)
# Returns a boolean value
AsyncAcceptStart( maxWaitMs )
Initiates a background thread to wait for and accept the next incoming TCP connection. The method will fail if an asynchronous operation is already in progress, or if the timeout expired. The timeout (in milliseconds) is passed in maxWaitMs. To wait indefinitely, set maxWaitMs to 0. Asynchronous accept operations can be aborted by calling AsyncAcceptAbort. When the async accept operation completes, the AsyncAcceptFinished property will become 1. If the accept was successful, the AsyncAcceptSuccess property is set to 1 and the connected socket can be retrieved via the AsyncAcceptSocket method. A debug log is available in the AsyncAcceptLog property. Returns 1 for success, 0 for failure.
AsyncConnectAbort( )
Aborts an asynchronous connect operation running in a background thread (started by calling AsyncConnectStart).
# hostname is a string (input)
# port is an integer (input)
# ssl is a boolean (input)
# maxWaitMs is an integer (input)
# Returns a boolean value
AsyncConnectStart( hostname, port, ssl, maxWaitMs )
Initiates a background thread to establish a TCP connection with a remote host:port. The method will fail if an asynchronous operation is already in progress, or if the timeout expired. The timeout (in milliseconds) is passed in maxWaitMs. To wait indefinitely, set maxWaitMs to 0. Set ssl = 1 to esablish an SSL connection. Asynchronous connect operations can be aborted by calling AsyncConnectAbort. When the async connect operation completes, the AsyncConnectFinished property will become 1. If the connect was successful, the AsyncConnectSuccess property is set to 1. A debug log is available in the AsyncConnectLog property. Returns 1 for success, 0 for failure.
AsyncDnsAbort( )
Aborts an asynchronous DNS lookup running in a background thread (started via the AsyncDnsStart method).
# hostname is a string (input)
# maxWaitMs is an integer (input)
# Returns a boolean value
AsyncDnsStart( hostname, maxWaitMs )
Initiates a background thread to do a DNS query (i.e. to resolve a hostname to an IP address). The method will fail if an asynchronous operation is already in progress, or if the timeout expired. The timeout (in milliseconds) is passed in maxWaitMs. To wait indefinitely, set maxWaitMs to 0. Asynchronous DNS lookups can be aborted by calling AsyncDnsAbort. When the async DNS operation completes, the AsyncDnsFinished property will become 1. If the DNS query was successful, the AsyncDnsSuccess property is set to 1. A debug log is available in the AsyncDnsLog property. Finally, the DNS query result (i.e. IP address) is available in nnn.nnn.nnn.nnn string form in the AsyncDnsResult property. Returns 1 for success, 0 for failure.
AsyncReceiveAbort( )
Aborts an asynchronous receive running in a background thread (started via one of the AsyncReceive* methods).
# Returns a boolean value
AsyncReceiveBytes( )
Initiates a background thread to receive bytes on an already-connected socket (ssl or non-ssl). Returns 1 for success, 0 for failure.
# numBytes is an integer (input)
# Returns a boolean value
AsyncReceiveBytesN( numBytes )
Initiates a background thread to receive exactly numBytes bytes on an already-connected socket (ssl or non-ssl). Returns 1 for success, 0 for failure.
# Returns a boolean value
AsyncReceiveString( )
Initiates a background thread to receive text on an already-connected socket (ssl or non-ssl). The component interprets the received bytes according to the charset specified in the StringCharset property. Returns 1 for success, 0 for failure.
# Returns a boolean value
AsyncReceiveToCRLF( )
Initiates a background thread to receive text on an already-connected socket (ssl or non-ssl). The asynchronous receive does not complete until a CRLF is received. The component interprets the received bytes according to the charset specified in the StringCharset property. Returns 1 for success, 0 for failure.
# matchStr is a string (input)
# Returns a boolean value
AsyncReceiveUntilMatch( matchStr )
Initiates a background thread to receive text on an already-connected socket (ssl or non-ssl). The asynchronous receive does not complete until the exact string specified by matchStr is received. The component interprets the received bytes according to the charset specified in the StringCharset property. Returns 1 for success, 0 for failure.
AsyncSendAbort( )
Aborts an asynchronous send running in a background thread (started via one of the AsyncSend* methods).
# byteData is a byte array (input)
# numBytes is an integer (input)
# Returns a boolean value
AsyncSendBytes( byteData, numBytes )
Initiates a background thread to send bytes on an already-connected socket (ssl or non-ssl). Returns 1 for success, 0 for failure.
# stringToSend is a string (input)
# Returns a boolean value
AsyncSendString( stringToSend )
Initiates a background thread to send text on an already-connected socket (ssl or non-ssl). Before sending, the stringToSend is first converted (if necessary) to the charset specified by the StringCharset property. Returns 1 for success, 0 for failure.
# port is an integer (input)
# backLog is an integer (input)
# Returns a boolean value
BindAndListen( port, backLog )
Binds a TCP socket to a port and configures it to listen for incoming connections. The size of the backlog is passed in backLog. The backlog is necessary when multiple connections arrive at the same time, or close enough in time such that they cannot be serviced immediately. (A typical value to use for backLog is 5.) This method should be called once prior to receiving incoming connection requests via the AcceptNextConnection or AsyncAcceptStart methods. Returns 1 for success, 0 for failure.
# url is a string (input)
# str is a CkString object (output)
BuildHttpGetRequest( url, str )
Convenience method for converting a full URL with query parameters into an HTTP GET request. The full HTTP GET request is returned as a string. Returns 1 for success, 0 for failure.
ClearSessionLog( )
Clears the contents of the SessionLog property.
# maxWaitMs is an integer (input)
Close( maxWaitMs )
Cleanly terminates and closes a TCP/IP (SSL or non-SSL) connection. The maxWaitMs applies to SSL connections because there is a handshake that occurs during secure channel shutdown.
# hostname is a string (input)
# port is an integer (input)
# ssl is a boolean (input)
# maxWaitMs is an integer (input)
# Returns a boolean value
Connect( hostname, port, ssl, maxWaitMs )
Establishes an SSL or non-SSL connection with a remote host:port. This is a blocking call. To initiate a non-blocking (asynchronous) connection in a background thread, call AsyncConnectStart. The maximum wait time (in milliseconds) is passed in maxWaitMs. To establish an SSL connection, set ssl = 1, otherwise set ssl = 0. Returns 1 for success, 0 for failure.
# hostname is a string (input)
# maxWaitMs is an integer (input)
# outStr is a CkString object (output)
# Returns a boolean value
DnsLookup( hostname, maxWaitMs, 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. Returns 1 for success, 0 for failure.
# Returns a CkCert object
GetMyCert( )
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.
# Returns a CkCert object
GetSslServerCert( )
Returns the SSL server's digital certificate. This method would only be called by the client-side of an SSL connection. It returns the certificate of the remote SSL server for the current SSL connection. If the socket is not connected, or is not connected via SSL, then a NULL reference is returned.
# Returns a boolean value
InitSslServer( cert )
SSL Server applications should call this method with the SSL server certificate to be used for SSL connections. Returns 1 for success, 0 for failure. SSL Server Example
# Returns a boolean value
IsUnlocked( )
Returns 1 if the component is unlocked.
# byteData is a CkByteData object (output)
# Returns a boolean value
ReceiveBytes( byteData )
Receives as much data as is immediately available on a connected TCP socket. If no data is immediately available, it waits up to MaxReadIdleMs milliseconds for data to arrive.
# numBytes is an integer (input)
# byteData is a CkByteData object (output)
# Returns a boolean value
ReceiveBytesN( numBytes, byteData )
Reads exactly numBytes bytes from a connected SSL or non-SSL socket. This method blocks until numBytes bytes are read or the read times out. The timeout is specified by the MaxReadIdleMs property (in milliseconds).
# Returns an integer value
ReceiveCount( )
Receives a 4-byte signed integer and returns the value received. Returns -1 on error.
# strOut is a CkString object (output)
# Returns a boolean value
ReceiveString( strOut )
Receives as much data as is immediately available on a TCP/IP or SSL socket. If no data is immediately available, it waits up to MaxReadIdleMs milliseconds for data to arrive. The incoming bytes are interpreted according to the StringCharset property and returned as a string. Returns 1 for success, 0 for failure.
# maxByteCount is an integer (input)
# outStr is a CkString object (output)
# Returns a boolean value
ReceiveStringMaxN( maxByteCount, 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.) Returns 1 for success, 0 for failure.
# lookForByte is an integer (input)
# outStr is a CkString object (output)
# Returns a boolean value
ReceiveStringUntilByte( lookForByte, 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. Returns 1 for success, 0 for failure.
# outStr is a CkString object (output)
# Returns a boolean value
ReceiveToCRLF( 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. Returns 1 for success, 0 for failure.
# lookForByte is an integer (input)
# outBytes is a CkByteData object (output)
# Returns a boolean value
ReceiveUntilByte( lookForByte, outBytes )
Receives bytes on the TCP/IP or SSL socket until a specific 1-byte value is read. Returns all the bytes up to and including the lookForByte.
# matchStr is a string (input)
# strOut is a CkString object (output)
# Returns a boolean value
ReceiveUntilMatch( matchStr, strOut )
Reads text from the connected TCP/IP or SSL socket until a matching string (matchStr) is received. Returns the text up to and including the matching string. As an example, to one might read the header of an HTTP request or a MIME message by reading up to the first double CRLF ("\r\n\r\n"). The incoming bytes are interpreted according to the charset specified by the StringCharset property. Returns 1 for success, 0 for failure. SSL Client Example
# filename is a string (input)
# Returns a boolean value
SaveLastError( filename )
Saves the last error information to an XML formatted file.
# byteData is a byte array (input)
# numBytes is an integer (input)
# Returns a boolean value
SendBytes( byteData, numBytes )
Sends bytes over a connected SSL or non-SSL socket. If transmission halts for more than MaxSendIdleMs milliseconds, the send is aborted. This is a blocking (synchronous) method. It returns only after the bytes have been sent. Returns 1 for success, 0 for failure.
# byteCount is an integer (input)
# Returns a boolean value
SendCount( byteCount )
(PreRelease) Sends a 4-byte signed integer on the connection. The receiver may call ReceiveCount to receive the integer. The SendCount and ReceiveCount methods are handy for sending byte counts prior to sending data. The sender would send a count followed by the data, and the receiver would receive the count first, and then knows how many data bytes it should expect to receive. Returns 1 for success, 0 for failure.
# stringToSend is a string (input)
# Returns a boolean value
SendString( stringToSend )
Sends a string over a connected SSL or non-SSL (TCP/IP) socket. If transmission halts for more than MaxSendIdleMs milliseconds, the send is aborted. The string is sent in the charset encoding specified by the StringCharset property.
This is a blocking (synchronous) method. It returns after the string has been sent. Returns 1 for success, 0 for failure. SSL Client Example
SetSslClientCert( cert )
To be documented soon...
# millisec is an integer (input)
SleepMs( millisec )
Convenience method to force the calling process to sleep for a number of milliseconds.
# code is a string (input)
# Returns a boolean value
UnlockComponent( code )
Unlocks the component allowing for the full functionality to be used. An arbitrary string can be passed to initiate a fully-functional 30-day trial. Returns 1 for success, 0 for failure.
# Returns a string
asyncAcceptLog( )
Contains the last-error information for an asynchronous accept operation.
# Returns a string
asyncConnectLog( )
Contains the last-error information for an asynchronous connect operation.
# Returns a string
asyncDnsLog( )
Contains the last-error information for an asynchronous DNS query.
# Returns a string
asyncDnsResult( )
The IP address of the last asynchronous DNS query completed. The IP address is in nnn.nnn.nnn.nnn string form.
# Returns a string
asyncReceiveLog( )
Contains the last-error information for an asynchronous receive operation.
# Returns a string
asyncReceivedString( )
Contains the string received in an asynchronous receive operation (when receiving a string asynchronously).
# Returns a string
asyncSendLog( )
Contains the last-error information for an asynchronous send operation.
# url is a string (input)
# Returns a string
buildHttpGetRequest( url )
Convenience method for converting a full URL with query parameters into an HTTP GET request. The full HTTP GET request is returned as a string.
# Returns a string
clientIpAddress( )
(PreRelease) 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".
# hostname is a string (input)
# maxWaitMs is an integer (input)
# Returns a string
dnsLookup( hostname, maxWaitMs )
Performs a DNS query to resolve a hostname to an IP address. The IP address is returned if successful. The maximum time to wait (in milliseconds) is passed in maxWaitMs. To wait indefinitely, set maxWaitMs = 0.
# Returns a string
lastErrorHtml( )
Error information in HTML format for the last method called.
# Returns a string
lastErrorText( )
Error information in plain-text format for the last method called.
# Returns a string
lastErrorXml( )
Error information in XML format for the last method called.
# Returns a string
myIpAddress( )
Returns the local IP address of the socket. 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.".
# Returns a string
receiveString( )
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.
# maxByteCount is an integer (input)
# Returns a string
receiveStringMaxN( maxByteCount )
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.)
# lookForByte is an integer (input)
# Returns a string
receiveStringUntilByte( lookForByte )
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.
# Returns a string
receiveToCRLF( )
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.
# matchStr is a string (input)
# Returns a string
receiveUntilMatch( matchStr )
Reads text from the connected TCP/IP or SSL socket until a matching string (matchStr) is received. Returns the text up to and including the matching string. As an example, to one might read the header of an HTTP request or a MIME message by reading up to the first double CRLF ("\r\n\r\n"). The incoming bytes are interpreted according to the charset specified by the StringCharset property. SSL Client Example
# Returns a string
remoteIpAddress( )
When a socket is connected, the remote IP address of the connected peer is available in this property.
# Returns a string
sessionLog( )
Contains a log of the bytes sent and received on this socket. The KeepSessionLog property must be set to 1 for logging to occur.
# Returns a string
sessionLogEncoding( )
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.
# Returns a string
sslProtocol( )
Selects the secure protocol to be used for secure (SSL) connections. Possible values are:
default
TLS 1.0
SSL 3.0
SSL 2.0
PCT 1.0
The default value is "default", which allows for the protocol to be selected dynamically at runtime based on the requirements of the server.
# Returns a string
stringCharset( )
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".
# Returns a string
version( )
The version of this component, such as "v1.0.0"
|