SDK Home Glossary Index Left Right Up

Socket


Section contents


Overview

This chapter describes the Socket class which provides a client endpoint to a protocol. It provides functions for socket creation, reading, writing, passive connection, active connection, setting addresses and querying addresses.

Defined in

csocket.oxh


Construction / destruction


NewSocket - Constructor

Usage

this& = NewSocket&:

Description

Create a socket object and returns a handle to the created object.

Return value
this& A handle which represents the created socket
Error Handling

If the object could not be created then an error is generated which should be trapped by an ONERR handler.

Example
  LOCAL this&

  this& = NewSocket&:
  DeleteSocket:(this&) 

DeleteSocket - Destructor

Usage

DeleteSocket:(BYREF this&)

Description

Destroys the socket object.

Arguments
BYREF this& A handle for a socket object. A zero value is written back into the variable
Example
  LOCAL this&

  this& = NewSocket&:
  DeleteSocket:(this&) 

Methods provided


SocketAcceptA - Accept a connection

Usage

SocketAcceptA:(this&,socket&,BYREF status&)

Description

The function facilitate client/server connection from a remote socket. The call extracts the first pending connection on a queue of sockets, the queue size being previously specified by SocketListen. On successful completion the blank socket is given the handle of the new socket and it may then be used to transfer data. After completion the accept socket may be used to make further connections with new blank sockets (see SocketOpen on how to open a blank socket).

SocketAcceptA may be used for protocols which do not have the KSIConnectionLess& flag in their protocol information.

Arguments
this& A handle for a socket object
socket& A handle for a socket object
BYREF status& The status of the asynchronous operation
Example
  LOCAL server&,socket&,blank&,address&,status&,err%

  server&=NewSocketServ&:
  socket&=NewSocket&:
  blank&=NewSocket&:
  address& = NewInetAddr4&:(KInetAddrLoop&,7)

  err% = SocketServConnect%:(server&,KSockDefaultMessageSlots&)
  err% = SocketOpen4%:(socket&,server&,KAfInet&,KSockStream&)
  err% = SocketBind%:(socket&,address&)
  err% = SocketListen%:(socket&,1)
  err% = SocketOpen%:(blank&,server&);
  SocketAcceptA:(socket&,blank&,status&)
  IOWAITSTATUS32 status&

  SocketClose:(blank&)
  SocketCancelAll:(socket&)
  SocketClose:(socket&)

  DeleteInetAddr:(address&)
  DeleteSocket:(blank&)
  DeleteSocket:(socket&)
  DeleteSocketServ:(server&) 
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.

See also

SocketAccept2A, SocketBind, SocketCancelAccept, SocketListen, SocketOpen


SocketAccept2A - Accept a connection

Usage

SocketAcceptA:(this&,socket&,des&,BYREF status&)

Description

The function facilitate client/server connection from a remote socket. The call extracts the first pending connection on a queue of sockets, the queue size being previously specified by SocketListen. On successful completion the blank socket is given the handle of the new socket and it may then be used to transfer data. After completion the accept socket may be used to make further connections with new blank sockets (see SocketOpen on how to open a blank socket).

An additional descriptor argument to receive data which may have been sent in a connect request. If there is a pending connection in the listen queue when SocketAccept2A is called, the call will complete immediately. Otherwise it will wait until a socket becomes available in the queue and complete asynchronously.

SocketAccept2A may be used for protocols which do not have the KSIConnectionLess& flag in their protocol information.

This routine must only be used with protocols which support the KSiConnectData& attribute in the protocol service information.

Arguments
this& A handle for a socket object
socket& A handle for a socket option
des& A handle for a descriptor object
BYREF status& The status of the asynchronous operation
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.

See also

SocketAcceptA, SocketBind, SocketCancelAccept, SocketListen


SocketBind - Set local address

Usage

err% = SocketBind%:(this&,address&)

Description

Use this function to set the local address of a socket. When a socket is opened it has no name associated with it, and binding is required so data can be routed to the socket. SocketBind should be called before SocketListen or SocketConnect. The address supplied should be a derived class specific to the particular protocol the socket was opened on.

Arguments
this& A handle for a socket object
address& A handle to a socket address object
Return value
err% An error code
Example
  LOCAL server&,socket&,blank&,address&,status&,err%

  server&=NewSocketServ&:
  socket&=NewSocket&:
  blank&=NewSocket&:
  address& = NewInetAddr&:(KInetAddrLoop&,7)

  err% = SocketServConnect%:(server&,KSockDefaultMessageSlots&)
  err% = SocketOpen4%:(socket&,server&,KAfInet&,KSockStream&)
  err% = SocketBind%:(socket&,address&)
  err% = SoxketListen%:(socket&,1)
  SocketAcceptA:(socket&,blank&,status&)
  IOWAITSTATUS32 status&

  SocketCancelAll:(socket&)
  SocketClose:(socket&)

  DeleteInetAddr:(address&)
  DeleteSocket:(blank&)
  DeleteSocket:(socket&)
  DeleteSocketServ:(server&) 

SocketCancelAccept - Cancel a connection

Usage

SocketCancelAccept:(this&)

Description

Cancel an accept operation.

Arguments
this& A handle for a socket object
See also

SocketAccept


SocketCancelAll

Usage

SocketCancelAll:(this&)

Description

Cancel all outstanding operations

Arguments
this& A handle for a socket object
See also

SocketCancelRead, SocketCancelRecv, SocketCancelSend, SocketCancelWrite


SocketCancelConnect - Cancel a connect

Usage

SocketCancelConnect:(this&)

Description

Cancel any connect operations.

Arguments
this& A handle for a socket object
See also

SocketConnect, SocketConnect2


SocketCancelIoctl

Usage

SocketCancelIoctl:(this&)

Description

Cancel any ioctl operations.

Arguments
this& A handle for a socket object
See also

SocketIoctl


SocketCancelRead

Usage

SocketCancelRead:(this&)

Description

Cancel a read operation.

Arguments
this& A handle for a socket object
See also

SocketCancelAll, SocketRead


SocketCancelRecv

Usage

SocketCancelRecv:(this&)

Description

Cancel any outstanding recv operations.

Arguments
this& A handle for a socket object
See also

SocketCancelAll, SocketRecvA, SocketRecvFromA, SocketRecvOneOrMoreA


SocketCancelSend

Usage

SocketCancelSend:(this&)

Description

Cancel any outstanding send operations.

Arguments
this& A handle for a socket object
See also

SocketCancelAll, SocketCancelWrite, SocketSend, SocketSendTo


SocketCancelWrite

Usage

SocketCancelWrite:(this&)

Description

Cancel any outstanding write operations.

Arguments
this& A handle for a socket object
See also

SocketCancelAll, SocketCancelSend, SocketWrite


SocketClose: - Close socket

Usage

SocketClose:(this&)

Description

Use this function to close a socket. If a socket has been opened using SocketOpen then it should be closed using SocketClose. This will ensure all associated resources are released.

Closing serves two distinct purposes:

If a socket is connected, then calling close is equivalent to calling SocketShutdownA with an argument of KStopNormal&, synchronously waiting for the request to complete, and then closing the IPC channel. If asynchronous or alternative methods of disconnecting are required then SocketShutdown should be called before SocketClose.

Arguments
this& A handle for a socket object
Example
  LOCAL server&
  LOCAL this&
  LOCAL err%
  LOCAL address&

  address& = NewInetAddr4&:(INET_ADDR(192,10,1,5),7)
  server& = NewSocketServ&:
  this& = NewSocket&:

  err% = SocketServConnect%(server&)
  err% = SocketOpen4:(this&,server&,KAfInet&,KSockStream&,KUndefinedProtocol&)
  SocketConnect:(socket&,address&,status&)
  IOWAITSTAT32 status&
  SocketClose:(socket&)

  DeleteInetAddr:(address&)
  DeleteSocket:(socket&)
  DeleteSocketServ:(server&)
Notes

If the SocketServ session on which a protocol was opened is closed, then all sockets associated with that session will be abortively closed and any further requests on the sockets will result in panics.

If a protocol has the flag KSiGracefulClose& in its protocol information, when SockClose is called on a connected socket, the socket will synchronously block until a response to a close request has been received or some other protocol condition causes the call to complete.

See also

SocketConnect, SocketConnect2


SocketConnectA - Connect to remote host

Usage

SocketConnectA:(this&,address&,BYREF status&)

Description

Use this functions to connect to a remote host. The address provided specifies the address of the remote host. A socket may only have one connect operation outstanding at any one time. Once the connect is completed, the socket is ready to send or receive data. If a socket is unbound — i.e. SocketBind has not been called yet — then it will automatically have a local address allocated.

SocketConnect is always required for protocols which do not have the KSiConnectionLess& flag in their protocol information. If a protocol has the KSiConnectionLess& flag, then SocketConnect may be used to set the address for all data sent from the socket, in which case SocketSend/SocketWrite may be used in addition to SocketSendTo.

Arguments
this& A handle for a socket object
address& A handle for a socket address object
BYREF status& The status of the asynchronous operation
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.

Example
  LOCAL server&
  LOCAL this&
  LOCAL err%
  LOCAL address&

  address& = NewInetAddr4&:(INET_ADDR(192,10,1,5),7)
  server& = NewSocketServ&:
  this& = NewSocket&:

  err% = SocketServConnect%(server&)
  err% = SocketOpen4:(this&,server&,KAfInet&,KSockStream&,KUndefinedProtocol&)
  SocketConnectA:(socket&,address&,status&)
  IOWAITSTAT32 status&
  SocketClose:(socket&)

  DeleteInetAddr:(address&)
  DeleteSocket:(socket&)
  DeleteSocketServ:(server&)
See also

SocketCancelConnect, SocketClose, SocketConnect2


SocketConnect2A - Connect to remote host

Usage

SocketConnect2A:(this&,address&,outDes&,inDes&,BYREF  status&)

Description

Use this functions to connect to a remote host. The address provided specifies the address of the remote host. Some protocols allow data to be sent in connect request packets which may be provided in the data-out descriptor. Some protocols may allow data to be sent in connect responses which may be collected in the data-in descriptor. A socket may only have one connect operation outstanding at any one time. Once the connect is completed, the socket is ready to send or receive data. If a socket is unbound — i.e. SocketBind has not been called yet — then it will automatically have a local address allocated.

SocketConnect2A is always required for protocols which do not have the KSiConnectionLess& flag in their protocol information. If a protocol has the KSiConnectionLess& flag, then SocketConnect2A may be used to set the address for all data sent from the socket, in which case SocketSend/SocketWrite may be used in addition to SocketSendTo.

This routine must only be used with protocols which support the KSiConnectData& attribute in the protocol service information.

Arguments
this& A handle for a socket object
address& A handle for a socket address object
outDes& A handle for a descriptor object
inDes& A handle for a descriptor object
BYREF status& The status of the asynchronous operation
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.

See also

SocketCancelConnect, SocketClose, SocketConnect


SocketGetDisconnectData

Usage

err% = SocketGetDisconnectData%:(this&,des&)

Description

Returns data in the descriptor des& that was included in a protocol disconnect message.

This routine must only be used with protocols which support the KSiDisconnectData& attribute in the protocol service information.

Arguments
this& A handle for a socket object
des& A handle to a descriptor object
Return value
err% The result of the operation
See also

ProtocolDescServiceInfo


SocketGetOpt - Get socket option

Usage

err% = SocketGetOpt$:(this&,optionName%,optionLevel%,des&)

Description

Use these functions to get a socket option. The socket server has options which are generic to all sockets and protocols may add specific options.

Arguments
this& A handle for a socket object
optionName% Specifies the socket option name
optionLevel% Specifies the socket option level
des& A handle for a descriptor object
Return value
err% The result of the operation
See also

SocketGetOptInt, SocketSetOpt, SocketSetOptInt


SocketGetOptInt - Get socket integer option

Usage

err% = SocketGetOpt$:(this&,optionName%,optionLevel%,BYREF option&)

Description

Use these functions to get an integer socket option. The socket server has options which are generic to all sockets and protocols may add specific options.

Arguments
this& A handle for a socket object
optionName% Specifies the socket option name
optionLevel% Specifies the socket option level
BYREF option& An integer which is used to hold the value of the option obtained
Return value
err% The result of the operation
See also

SocketGetOpt, SocketSetOpt, SocketSetOptInt


SocketInfo - Get socket protocol information

Usage

err% = SocketInfo%:(this&,buffer&)

Description

Use this function to get information in the protocol description for the protocol which a socket is opened on.

Arguments
this& A handle for a socket object
buffer& A handle for a protocol description object
Return value
err% The result of the operation

SocketIoctlA

Usage

SocketIoctlA:(this&,command%,BYREF status&,des&,level%)

Description

Use this function to apply an asynchronous control operation on a socket. Data may be passed and received if a descriptor address is provided as an argument. Only one SocketIoctlA operation may be outstanding for each socket.

Arguments
this& A handle for a socket object
command% Specifies the ioctl command to perform
BYREF status& The status of the asynchronous operation
des& A handle for a descriptor object
level% Control operation level
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.


SocketListen - Listen for incoming connections

Usage

err% = SocketListen%:(this&,size%)

Description

Use the function to set up a socket to listen for incoming connections. Before calling this procedure a socket should be opened on a specific protocol using SocketOpen and the socket should be bound to a local address using SocketBind. SocketListen creates a queue to hold incoming connections which can be married with blank sockets using SocketAccept. The call also allows data to be sent back to connecting peers if a protocol allows data to be passed in connect responses. Once a listen queue has been created it will continue to allow peers to connect until it is full, at which point it will reject any incoming connections as specified by protocol behaviour. When a socket is accepted by the client a space is made available in the queue.

Arguments
this& A handle for a socket object
size% The size of the listen queue
Return value
err% The result of the operation
Example
  LOCAL server&,socket&,blank&,address&,status&,err%

  server&=NewSocketServ&:
  socket&=NewSocket&:
  blank&=NewSocket&:
  address& = NewInetAddr&:(KInetAddrLoop&,7)

  err% = SocketServConnect%:(server&,KSockDefaultMessageSlots&)
  err% = SocketOpen4%:(socket&,server&,KAfInet&,KSockStream&)
  err% = SocketBind%:(socket&,address&)
  err% = SoxketListen%:(socket&,1)
  SocketAcceptA:(socket&,blank&,status&)
  IOWAITSTATUS32 status&

  SocketCancelAll:(socket&)
  SocketClose:(socket&)

  DeleteInetAddr:(address&)
  DeleteSocket:(blank&)
  DeleteSocket:(socket&)
  DeleteSocketServ:(server&) 
See also

SocketAcceptA, SocketAccept2A, SocketBind, SocketListen2


SocketListen2 - Listen for incoming connections

Usage

err% = SocketListen2%:(this&,size%,des&)

Description

Use the function to set up a socket to listen for incoming connections. Before calling this procedure a socket should be opened on a specific protocol using SocketOpen and the socket should be bound to a local address using SocketBind. SocketListen creates a queue to hold incoming connections which can be married with blank sockets using SocketAccept. The call also allows data to be sent back to connecting peers if a protocol allows data to be passed in connect responses. Once a listen queue has been created it will continue to allow peers to connect until it is full, at which point it will reject any incoming connections as specified by protocol behaviour. When a socket is accepted by the client a space is made available in the queue.

This routine must only be used with protocols which support the KSiConnectData& attribute in the protocol service information.

Arguments
this& A handle for a socket object
size% The size of the listen queue
des& A handle for a descriptor object
Return value
err% The result of the operation
See also

SocketAcceptA, SocketAccept2A, SocketBind, SocketListen


SocketLocalName - Get local name

Usage

SocketLocalName:(this&,address&)

Description

Use this function to get the local address of a socket. The local address is set either by calling SocketBind or it is automatically set when SocketConnect is called. If a socket is created through SocketAccept then a socket will inherit the port of its parent unless otherwise specified by a protocol’s behavior. Depending on a protocol implementation, additional information may be gained through this call.

Arguments
this& A handle for a socket object
address& A handle for a socket address object
See also

SocketRemoteName


SocketLocalPort - Get local port

Usage

port% = SocketLocalPort%:(this&)

Description

Use this function to get the local port of a socket. The local ports is set either by calling SocketBind or it is automatically set when SocketConnect is called. If a socket is created through SocketAccept then a socket will inherit the port of its parent unless otherwise specified by a protocol’s behavior. Depending on a protocol implementation, additional information may be gained through this call.

Arguments
this& A handle for a socket object
Return
port% The port of the local connection
See also

SocketSetLocalPort


SocketName

Usage

err% = SocketName%:(this&,des&)

Description

<TBS>

Arguments
this& A handle for a socket object
des& A handle for a descriptor object
Return
err% The result of the operation

SocketOpen - Open a socket

Usage

err% = SocketOpen%:(this&,server&)

Description

Opens a blank channel to the socket server. A socket opened in this way has can be used with the SocketAcceptA function.

Arguments
this& A handle for a socket object
server& The socket server session; a SocketServ object
Return value
err% The result of the operation
See also

SocketAccept, SocketClose, SocketOpen2, SocketOpen4


SocketOpen2 - Open a socket

Usage

err% = SocketOpen2%:(this&,server&,name$)

Description

The opens a channel to a protocol protocol identified by name. If a socket is the first to be opened for a protocol it will have the additional affect of loading the protocol in the socket server.

Arguments
this& A handle for a socket object
server& The socket server session; a SocketServ object
name$ The name of a protocol
Return value
err% The result of the operation
See also

SocketClose, SocketOpen, SocketOpen4


SocketOpen4 - Open a socket

Usage

err% = SocketOpen4%:(this&,server&,family&,sockType&,protocol&)

Description

The opens a channel to a protocol protocol identified by contstants. If a socket is the first to be opened for a protocol it will have the additional affect of loading the protocol in the socket server.

Arguments
this& A handle for a socket object
server& The socket server session; a handle to a SocketServ object
family& Specifies the address family
sockType& Specifies the socket type
protocol& Specifies the protocol
Return value
err% The result of the operation
Example
  LOCAL this&,server&,address&,err% 

  address& = NewInetAddr4&:(INET_ADDR(192,10,1,5),7)
  server& = NewSocketServ&:
  this& = NewSocket&:

  err% = SocketServConnect%(server&)
  err% = SocketOpen4:(this&,server&,KAfInet&,KSockStream&,KUndefinedProtocol&)
  SocketConnect:(socket&,address&,status&)
  IOWAITSTAT32 status&
  SocketClose:(socket&)

  DeleteInetAddr:(address&)
  DeleteSocket:(socket&)
  DeleteSocketServ:(server&)
See also

SocketClose, SocketOpen, SocketOpen2


SocketReadA

Usage

SocketReadA:(this&, des&,BYREF status%)

Description

Use this function to receive data from a remote host.

SocketReadA should only be used with connected sockets.

On completion the descriptor will be filled with data up to its maximum length. A socket may only have one receive operation outstanding at any one time.

Arguments
this& A handle for a socket object
des& A handle for a descriptor object
BYREF status& The status of the asynchronous operation
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.

See also

SocketRecvA, SocketRecv2A, SocketFromA, SocketRecvFrom2A, SocketRecvOneOrMore2A


SocketRecvA

Usage

SocketRecvA:(this&,des&,flags&,BYREF status%)

Description

Use this function to receive data from a remote host. Flags are provided to add protocol specific information.

SocketRecvA should only be used with connected sockets.

On completion the descriptor will be filled with data up to its maximum length. A socket may only have one receive operation outstanding at any one time.

If a protocol’s information flag is marked with KSiPeekData&, then KSockReadPeek& may be provided as a flag to SockRecvA. All other flags are protocol specific.

Arguments
this& A handle for a socket object
des& A handle for a descriptor object
flags& Specifies socket recv flags
BYREF status& The status of the asynchronous operation
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.

See also

SocketReadA, SocketRecv2A, SocketFromA, SocketRecvFrom2A, SocketRecvOneOrMore2A


SocketRecv2A

Usage

SocketRecv2A:(this&,des&,flags&,BYREF status%,BYREF xfrLength&)

Description

Use this function to receive data from a remote host. Flags are provided to add protocol specific information.

SocketRecv2A should only be used with connected sockets.

On completion the descriptor will be filled with data up to its maximum length. If less than the maximum length of the descriptor is available to be filled then an extra length argument can be provided. A socket may only have one receive operation outstanding at any one time.

If a protocol’s information flag is marked with KSiPeekData&, then KSockReadPeek& may be provided as a flag to SockRecv2A. All other flags are protocol specific.

Arguments
this& A handle for a socket object
des& A handle for a descriptor object
flags& Specifies socket recv flags
BYREF status& The status of the asynchronous operation
BYREF xfrLength& A handle for a socket transfer length object
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.

See also

SocketReadA, SocketRecvA, SocketFromA, SocketRecvFrom2A, SocketRecvOneOrMore2A


SocketRecvFromA

Usage

SocketRecvFromA:(this&,des&,address&,flags&,BYREF status%)

Description

Use this function to receive data from a remote host. Flags are provided to add protocol specific information.

SocketRecvFromA should be used on unconnected sockets where a source address is returned.

On completion the descriptor will be filled with data up to its maximum length. A socket may only have one receive operation outstanding at any one time.

If a protocol’s information flag is marked with KSiPeekData&, then KSockReadPeek& may be provided as a flag to SockRecvFromA. All other flags are protocol specific.

Arguments
this& A handle for a socket object
des& A handle for a descriptor object
address& A handle to a socket address which is a remote source address for unconnected receives
flags& Specifies socket recv flags
BYREF status& The status of the asynchronous operation
See also

SocketReadA, SocketRecvA, SocketRecv2A, SocketRecvFrom2A, SocketRecvOneOrMore2A


SocketRecvFrom2A

Usage

SocketRecvFrom2A:(this&,des&,address&,flags&,BYREF status%,BYREF xfrLength&)

Description

Use this function to receive data from a remote host. Flags are provided to add protocol specific information.

SocketRecvFrom2A should be used on unconnected sockets where a source address is returned.

On completion the descriptor will be filled with data up to its maximum length. If less than the maximum length of the descriptor is available to be filled then an extra length argument can be provided. A socket may only have one receive operation outstanding at any one time.

If a protocol’s information flag is marked with KSiPeekData&, then KSockReadPeek& may be provided as a flag to SockRecvFrom2A. All other flags are protocol specific.

Arguments
this& A handle for a socket object
des& A handle for a descriptor object
address& A handle to a socket address which is a remote source address for unconnected receives
flags& Specifies socket recv flags
BYREF status& The status of the asynchronous operation
BYREF xfrLength& A handle for a socket transfer length object
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.

See also

SocketReadA, SocketRecvA, SocketRecvFrom, SocketRecvOneOrMore2A


SocketRecvOneOrMoreA

Usage

SocketRecvOneOrMoreA:(this&,des&,flags&,BYREF status%)

Description

Use this function to receive data from a remote host. Flags are provided to add protocol specific information.

SocketRecvOneOrMoreA should only be used with connected sockets.

On completion the descriptor will be filled with data up to its maximum length. If less than the maximum length of the descriptor is available to be filled then an extra length argument can be provided. A socket may only have one receive operation outstanding at any one time.

If a protocol’s information flag is marked with KSiPeekData&, then KSockReadPeek& may be provided as a flag to SockRecvOneOrMoreA. All other flags are protocol specific.

Arguments
this& A handle for a socket object
des& A handle for a descriptor object
flags& Specifies socket recv flags
BYREF status& The status of the asynchronous operation
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.

See also

SocketReadA, SocketRecvA

Notes

This routine should no longer be used as a serious flaw has been found in it's implementation; instead use SocketRecvOneOrMore2A


SocketRecvOneOrMore2A

Usage

SocketRecvOneOrMore2A:(this&,des&,flags&,length&,BYREF status%)

Description

Use this function to receive data from a remote host. Flags are provided to add protocol specific information.

SocketRecvOneOrMore2A should only be used with connected sockets.

On completion the descriptor will be filled with data up to its maximum length. If less than the maximum length of the descriptor is available to be filled then an extra length argument can be provided. A socket may only have one receive operation outstanding at any one time.

If a protocol’s information flag is marked with KSiPeekData&, then KSockReadPeek& may be provided as a flag to SockRecvOneOrMore2A. All other flags are protocol specific.

Arguments
this& A handle for a socket object
des& A handle for a descriptor object
flags& Specifies socket recv flags
length& A socket transfer length for the returned length
BYREF status& The status of the asynchronous operation
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.

See also

SocketReadA, SocketRecvA


SocketRemoteName - Get the remote name

Usage

SocketRemoteName:(this&,address&)

Description

Use this function to get the remote name of a socket. The remote name of a socket is associated with the remote host a socket is connected to. The remote name is only valid for a connected socket. A socket is either connected through calling SocketConnect or SocketAccept.

Arguments
this& A handle for a socket object
address& A handle for a socket address object
Example
  LOCAL server&,socket&,blank&,address&,remote&,status&,err%

  server&=NewSocketServ&:
  socket&=NewSocket&:
  blank&=NewSocket&:
  address& = NewInetAddr4&:(KInetAddrLoop&,7)
  remote& = NewInetAddr&:

  err% = SocketServConnect%:(server&,KSockDefaultMessageSlots&)
  err% = SocketOpen4%:(socket&,server&,KAfInet&,KSockStream&)
  err% = SocketBind%:(socket&,address&)
  err% = SocketListen%:(socket&,1)
  err% = SocketOpen%:(blank&,server&);
  SocketAcceptA:(socket&,blank&,status&)
  IOWAITSTATUS32 status&

  SocketRemoteName:(blank&,remote&)
  PRINT InetAddrOutput$:(remote&)

  SocketClose:(blank&)
  SocketCancelAll:(socket&)
  SocketClose:(socket&)

  DeleteInetAddr:(remote&)
  DeleteInetAddr:(address&)
  DeleteSocket:(blank&)
  DeleteSocket:(socket&)
  DeleteSocketServ:(server&) 
See also

SocketLocalName


SocketSendA

Usage

SocketSendA:(this&, des&, flags&, BYREF status&)

Description

Use this function to send data to a remote host. Flags are provided to add protocol specific information.

SocketSendA should only be used with connected sockets.

A socket may only have one send operation in progress at any one time.

Arguments
this& A handle for a socket object
des& A handle for a descriptor object
flags& Specifies socket send flags
BYREF status& The status of the asynchronous operation
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.

See also

SocketSend2A, SocketSentToA, SocketSendTo2A, SocketWriteA


SocketSend2A

Usage

SocketSend2A:(this&, des&, flags&, BYREF status&, xfrLength&)

Description

Use this function to send data to a remote host. Flags are provided to add protocol specific information.

SocketSend2A should only be used with connected sockets.

An additional argument can be provided to indicate the amount of data sent. The length of the descriptor indicates the amount of data to be sent. A socket may only have one send operation in progress at any one time.

Arguments
this& A handle for a socket object
des& A handle for a descriptor object
flags& Specifies socket send flags
BYREF status& The status of the asynchronous operation
xfrLength& A handle for a socket transfer length object
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.


SocketSendToA

Usage

SocketSendToA:(this&, des&, address&, flags&, BYREF status&)

Description

Use this function to send data to a remote host. Flags are provided to add protocol specific information.

SocketSendToA should be used with a destination address on unconnected sockets.

A socket may only have one send operation in progress at any one time.

Arguments
this& A handle for a socket object
des& A handle for a descriptor object
address& A handle for a socket address object
flags& Specifies socket send flags
BYREF status& The status of the asynchronous operation
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.

See also

SocketSendA, SocketSendTo2A, SocketWriteA


SocketSendTo2A

Usage

SocketSendTo2A:(this&, des&, address&, flags&, BYREF status&, xfrLength&)

Description

Use this function to send data to a remote host. Flags are provided to add protocol specific information.

SocketSendTo2A should be used with a destination address on unconnected sockets.

An additional argument can be provided to indicate the amount of data sent. The length of the descriptor indicates the amount of data to be sent. A socket may only have one send operation in progress at any one time.

Arguments
this& A handle for a socket object
des& A handle for a descriptor object
address& A handle for a socket address object
flags& Specifies socket send flags
BYREF status& The status of the asynchronous operation
xfrLength& A handle for a socket transfer length object
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.

See also

SocketSendA, SocketSendToA, SocketWriteA


SocketSetLocalPort - Set local port

Usage

err% = SocketSetLocalPort%:(this&,port&)

Description

Use this function to set the local port of a socket. Setting the local port is equivalent to calling SocketBind with only the port set in the address.

Arguments
this& A handle for a socket object
port& The port to set
Return value
err% An error code
See also

SocketLocalPort


SocketSetOpt - Set socket option

Usage

err% = SocketSetOpt$:(this&, optionName%, optionLevel%, des&))

Description

Use this function to set a socket option. The socket server has options which are generic to all sockets and protocols may add specific options.

Arguments
this& A handle for a socket object
optionName% Specifies the socket option name
optionLevel% Specifies the socket option level
des& A handle for a descriptor object
Return value
err% The result of the operation
See also

SocketGetOpt, SocketGetOptInt, SocketSetOptInt


SocketSetOptInt - Set socket integer option

Usage

err% = SocketSetOptInt$:(this&, optionName%, optionLevel%, option&))

Description

Use this function to set an integer socket option. The socket server has options which are generic to all sockets and protocols may add specific options.

Arguments
this& A handle for a socket object
optionName% Specifies the socket option name
optionLevel% Specifies the socket option level
option& The value of the option to be set
Return value
err% The result of the operation
See also

SocketGetOpt, SocketGetOptInt, SocketSetOpt


SocketShutdownA

Usage

SocketShutdownA:(this&,how&,BYREF status&)

Description

Use these functions to asynchronously shutdown a connected socket. The shutdown method allows input and output to be individually stopped for a protocol endpoint. For protocols which support data-in disconnect message, additional arguments are provided.

Arguments
this& A handle for a socket object
how& The shutdown type to be performed
BYREF status& The status of the asynchronous operation
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.

Notes

SocketShutdownA can be used for protocols which do not have the KSiConnectionLess& flag in their protocol information.

There is no way to cancel a socket shutdown once it has started.

See also

SocketShutdown2A


SocketShutdown2A

Usage

SocketShutdown2A:(this&,how&,outDes&,inDes&,BYREF status&)

Description

Use these functions to asynchronously shutdown a connected socket. The shutdown method allows input and output to be individually stopped for a protocol endpoint. For protocols which support data-in disconnect message, additional arguments are provided.

This routine must only be used with protocols which support the KSiConnectData& attribute in the protocol service information.

Arguments
this& A handle for a socket object
how& The shutdown type to be performed
outDes& A handle for a descriptor object
inDes& A handle for a descriptor object
BYREF status& The status of the asynchronous operation
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.

Notes

SocketShutdown2A can be used for protocols which do not have the KSiConnectionLess& flag in their protocol information.

There is no way to cancel a socket shutdown once it has started.

See also

SocketShutdownA


SocketTransfer

Usage

err% = SocketTransfer$:(this&,server&,des&))

Description

<TBS>

Arguments
this& A handle for a socket object
server& The socket server session; a handle to a SocketServ object
des& A handle for a descriptor object
Return value
err% The result of the operation

SocketWrite

Usage

err% = SocketWrite%:(this&,str$)

Description

Use this function to send data to a remote host.

SocketWriteA should only be used with connected sockets.

A socket may only have one send operation in progress at any one time.

Arguments
this& A handle for a socket object
str$ A string to write
Return value
err% The result of the operation
See also

SocketSendA, SocketSendToA, SocketSendTo2A


SocketWriteA

Usage

SocketWriteA:(this&,des&,BYREF&nbsstatus&)

Description

Use this function to send data to a remote host.

SocketWriteA should only be used with connected sockets.

An additional argument can be provided to indicate the amount of data sent. The length of the descriptor indicates the amount of data to be sent. A socket may only have one send operation in progress at any one time.

Arguments
this& A handle for a socket object
des& A handle for a descriptor object
BYREF status& The status of the asynchronous operation
Error Handling

If the status& object cannot be created then an error is generated which should be trapped by an ONERR handler.

See also

SocketSendA, SocketSendToA, SocketSendTo2A


  SDK Home Glossary Index Left Right Up