| Chapter 9. The Sockets (SOCK) Component | ||
|---|---|---|
 | Part II. C-Language Components |  |
Chapter 9. The Sockets (SOCK) Component
Provides the types for working with the Internet Protocol (TCP/IP and UDP/IP) for both client and server.
tcpsocket
Description
A tcpsocket object can be created via a call to the
new() of the tcpsocket type or else
because of a connection to a tcpsocketserver object. This
object provides TCP/IP socket support for communication.
Type Tags
None
Object Value
Objects of type tcpsocket have no value, and it is an error to try to get or set this value.
tcpsocket.new()
Description
Opens a TCP/IP connection to the requested address on the requested port using the local port that was specified (if none was provided then one will be selected automatically).
Prototype
tcpsocket.new (
string destinationporttimeouterror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| destination | None | string | The name or IP address of the destination to which to connect. This must include the port number, ie. "192.168.0.1:80" or "www.superbase.com:25". |
| port | .nul | integer | The local port number to use. If none is specified then a port will automatically be selected. |
| timeout | .inf | integer | The time in microseconds to wait before deciding that the operation has failed. |
| error | .nul | integer |
Specifies an object which is used to output any error code generated during
creation of the tcpsocket object. If
error is not specified or is
.nul then any error which occurs during object
creation will halt the program. If an error object is specified and
an error occurs during object creation then the error code is
output into that object and the new method
returns .nul.
|
Properties
| Property | Type | Description |
|---|---|---|
| _ | type(*) | This property is provided for use by the user to attach any object of any type to the type in which this property is provided. |
| __ | type(*) | This property is provided for use by the user to attach any object of any type to the type in which this property is provided. It has the additional feature of being marked with the resolve keyword, so that object resolution can continue down this property. |
| destination | string | A read-only string giving the destination in "a.b.c.d:p" format. |
| port | integer | A read-only integer giving the local port number being used (even if it was an automatically generated one). |
| type | type | Specifies the tcpsocket type object. |
Methods
receiveblob()
Description
Returns a blob or .nul. If the error value returned is
equal to 64 (normal end of data), then it may not be safe to continue
using the socket (the other end may have closed it).
Prototype
tcpsocketvar.receiveblob (
integer timeouterror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| timeout | .inf | integer | The time in microseconds to wait before deciding that the operation has failed. |
| error | .nul | integer |
Specifies an object that is used to output any error code generated during the
execution of the method. This parameter must be an object, not an
integer value. If error
is not specified or is .nul then any error
that occurs during object creation will halt the program. If an
error object is specified and an error occurs during execution
then the error code is output into that object and the method
returns .nul.
|
receivestring()
Description
Returns a string or .nul. If the error value returned is
equal to 64 (normal end of data), then it may not be safe to continue
using the socket (the other end may have closed it).
Prototype
tcpsocketvar.receivestring (
integer charsizelbotimeouterror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| charsize | 2 | integer |
The number of bytes per character, which must be greater than 0. If this value
is equal to .nul or .inf
then the result will be .nul.
|
| lbo | .true | boolean |
Indicates whether characters have been stored with the least significant byte
first (.true) or with the most significant
byte first (.false). If this value is equal to
.nul or .inf then the
result will be .nul.
|
| timeout | .inf | integer | The time in microseconds to wait before deciding that the operation has failed. |
| error | .nul | integer |
Specifies an object that is used to output any error code generated during the
execution of the method. This parameter must be an object, not an
integer value. If error
is not specified or is .nul then any error
that occurs during object creation will halt the program. If an
error object is specified and an error occurs during execution
then the error code is output into that object and the method
returns .nul.
|
sendblob()
Description
Sends the contents of blob to the destination.
Prototype
tcpsocketvar.sendblob (
blob blobtimeouterror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| blob | .inf | blob | This parameter is required. The blob contains what is being sent to the destination. |
| timeout | .inf | integer | The time in microseconds to wait before deciding that the operation has failed. |
| error | .nul | integer |
Specifies an object that is used to output any error code generated during the
execution of the method. This parameter must be an object, not an
integer value. If error
is not specified or is .nul then any error
that occurs during object creation will halt the program. If an
error object is specified and an error occurs during execution
then the error code is output into that object and the method
returns .nul.
|
sendstring()
Description
Sends the contents of string to the destination.
Prototype
tcpsocketvar.sendstring (
string stringcharsizelbotimeouterror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| string | None | string | This parameter is required. The string contains what is being sent to the destination. |
| charsize | 2 | integer |
The number of bytes per character, which must be greater than 0. If this value
is equal to .nul or .inf
then the result will be .nul.
|
| lbo | .true | boolean |
Indicates whether characters have been stored with the least significant byte
first (.true) or with the most significant
byte first (.false). If this value is equal to
.nul or .inf then the
result will be .nul.
|
| timeout | .inf | integer | The time in microseconds to wait before deciding that the operation has failed. |
| error | .nul | integer |
Specifies an object that is used to output any error code generated during the
execution of the method. This parameter must be an object, not an
integer value. If error
is not specified or is .nul then any error
that occurs during object creation will halt the program. If an
error object is specified and an error occurs during execution
then the error code is output into that object and the method
returns .nul.
|