OSRTSocket Class Reference
[TCP/IP or UDP Socket Classes]

Wrapper class for TCP/IP or UDP sockets. More...

#include <OSRTSocket.h>

List of all members.

Public Member Functions

EXTRTMETHOD OSRTSocket ()
 This is the default constructor.
EXTRTMETHOD OSRTSocket (OSRTSOCKET socket, OSBOOL ownership=FALSE)
 This constructor initializes an instance by using an existing socket.
EXTRTMETHOD OSRTSocket (const OSRTSocket &socket)
 The copy constructor.
EXTRTMETHOD ~OSRTSocket ()
 The destructor.
EXTRTMETHOD OSRTSocketaccept (OSIPADDR *destIP=0, int *port=0)
 This method permits an incoming connection attempt on a socket.
EXTRTMETHOD int bind (OSIPADDR addr, int port)
 This method associates a local address with a socket.
EXTRTMETHOD int bindUrl (const char *url)
 This method associates a local address with a socket.
EXTRTMETHOD int bind (const char *pAddrStr, int port)
 This method associates a local address with a socket.
int bind (int port)
 This method associates only a local port with a socket.
EXTRTMETHOD int blockingRead (OSOCTET *pbuf, size_t readBytes)
 This method receives data from the connected socket.
EXTRTMETHOD int close ()
 This method closes this socket.
EXTRTMETHOD int connect (const char *host, int port)
 This method establishes a connection to this socket.
EXTRTMETHOD int connectUrl (const char *url)
 This method establishes a connection to this socket.
OSBOOL getOwnership ()
 Returns the ownership of underlying O/S socket.
OSRTSOCKET getSocket () const
 This method returns the handle of the socket.
int getStatus ()
 Returns a completion status of last operation.
EXTRTMETHOD int listen (int maxConnections)
 This method places a socket into a state where it is listening for an incoming connection.
EXTRTMETHOD int recv (OSOCTET *pbuf, size_t bufsize)
 This method receives data from a connected socket.
void setOwnership (OSBOOL ownership)
 Transfers an ownership of the underlying O/S socket to or from the socket object.
EXTRTMETHOD int send (const OSOCTET *pdata, size_t size)
 This method sends data on a connected socket.

Static Public Member Functions

static EXTRTMETHOD const char * addrToString (OSIPADDR ipAddr, char *pAddrStr, size_t bufsize)
 This method converts an IP address to its string representation.
static EXTRTMETHOD OSIPADDR stringToAddr (const char *pAddrStr)
 This method converts a string containing an Internet Protocol dotted address into a proper OSIPADDR address.

Protected Attributes

OSRTSOCKET mSocket
 handle of the socket
OSBOOL mOwner
 indicates this class owns the socket

Detailed Description

Wrapper class for TCP/IP or UDP sockets.

Definition at line 50 of file OSRTSocket.h.


Constructor & Destructor Documentation

EXTRTMETHOD OSRTSocket::OSRTSocket (  ) 

This is the default constructor.

It initializes all internal members with default values and creates a new socket structure. Use getStatus() method to determine has error occurred during the initialization or not.

EXTRTMETHOD OSRTSocket::OSRTSocket ( OSRTSOCKET  socket,
OSBOOL  ownership = FALSE 
)

This constructor initializes an instance by using an existing socket.

Parameters:
socket An existing socket handle.
ownership Boolean flag that specifies who is the owner of the socket. If it is TRUE then the socket will be destroyed in the destructor. Otherwise, the user is responsible to close and destroy the socket.
EXTRTMETHOD OSRTSocket::OSRTSocket ( const OSRTSocket socket  ) 

The copy constructor.

The copied instance will have the same socket handle as the original one, but will not be the owner of the handle.

EXTRTMETHOD OSRTSocket::~OSRTSocket (  ) 

The destructor.

This closes socket if the instance is the owner of the socket.


Member Function Documentation

EXTRTMETHOD OSRTSocket* OSRTSocket::accept ( OSIPADDR *  destIP = 0,
int *  port = 0 
)

This method permits an incoming connection attempt on a socket.

It extracts the first connection on the queue of pending connections on the socket. It then creates a new socket and returns an instance of the new socket. The newly created socket will handle the actual connection and has the same properties as the original socket.

Parameters:
destIP Optional pointer to a buffer that receives the IP address of the connecting entity. It may be NULL.
port Optional pointer to a buffer that receives the port of the connecting entity. It may be NULL.
Returns:
An instance of the new socket class. NULL, if error occur. Use OSRTSocket::getStatus method to obtain error code.
See also:
rtxSocketAccept
static EXTRTMETHOD const char* OSRTSocket::addrToString ( OSIPADDR  ipAddr,
char *  pAddrStr,
size_t  bufsize 
) [static]

This method converts an IP address to its string representation.

Parameters:
ipAddr The IP address to be converted.
pAddrStr Pointer to the buffer to receive a string with the IP address.
bufsize Size of the buffer.
Returns:
Pointer to a string with IP-address. NULL, if error occur.
int OSRTSocket::bind ( int  port  )  [inline]

This method associates only a local port with a socket.

It is used on an unconnected socket before subsequent calls to the OSRTSocket::connect or OSRTSocket::listen methods.

Parameters:
port The local port number to assign to the socket.
Returns:
Completion status of operation:
  • 0 = success,
  • negative return value is error.
See also:
rtxSocketBind
bind ()

Definition at line 183 of file OSRTSocket.h.

EXTRTMETHOD int OSRTSocket::bind ( const char *  pAddrStr,
int  port 
)

This method associates a local address with a socket.

It is used on an unconnected socket before subsequent calls to the OSRTSocket::connect or OSRTSocket::listen methods.

Parameters:
pAddrStr Null-terminated character string representing a number expressed in the Internet standard "." (dotted) notation.
port The local port number to assign to the socket.
Returns:
Completion status of operation:
  • 0 = success,
  • negative return value is error.
See also:
rtxSocketBind
EXTRTMETHOD int OSRTSocket::bind ( OSIPADDR  addr,
int  port 
)

This method associates a local address with a socket.

It is used on an unconnected socket before subsequent calls to the OSRTSocket::connect or OSRTSocket::listen methods.

Parameters:
addr The local IP address to assign to the socket.
port The local port number to assign to the socket.
Returns:
Completion status of operation:
  • 0 = success,
  • negative return value is error.
See also:
rtxSocketBind
EXTRTMETHOD int OSRTSocket::bindUrl ( const char *  url  ) 

This method associates a local address with a socket.

It is used on an unconnected socket before subsequent calls to the OSRTSocket::connect or OSRTSocket::listen methods. This version of the method allows a URL to be used instead of address and port number.

Parameters:
url Univeral resource locator (URL) string.
Returns:
Completion status of operation:
  • 0 = success,
  • negative return value is error.
See also:
rtxSocketBind
EXTRTMETHOD int OSRTSocket::blockingRead ( OSOCTET *  pbuf,
size_t  readBytes 
)

This method receives data from the connected socket.

In this case, the connection is blocked until either the requested number of bytes is received or the socket is closed or an error occurs.

Parameters:
pbuf Pointer to the buffer for the incoming data.
readBytes Number of bytes to receive.
Returns:
If no error occurs, returns the number of bytes received. Otherwise, the negative value is error code.
EXTRTMETHOD int OSRTSocket::close (  ) 

This method closes this socket.

Returns:
Completion status of operation:
  • 0 = success,
  • negative return value is error.
See also:
rtxSocketClose
EXTRTMETHOD int OSRTSocket::connect ( const char *  host,
int  port 
)

This method establishes a connection to this socket.

It is used to create a connection to the specified destination. When the socket call completes successfully, the socket is ready to send and receive data.

Parameters:
host Null-terminated character string representing a number expressed in the Internet standard "." (dotted) notation.
port The destination port to connect.
Returns:
Completion status of operation:
  • 0 = success,
  • negative return value is error.
See also:
rtxSocketConnect
EXTRTMETHOD int OSRTSocket::connectUrl ( const char *  url  ) 

This method establishes a connection to this socket.

It is used to create a connection to the specified destination. In this version, destination is specified using a URL.

Parameters:
url Univeral resource locator (URL) string.
Returns:
Completion status of operation:
  • 0 = success,
  • negative return value is error.
See also:
rtxSocketConnect
OSBOOL OSRTSocket::getOwnership (  )  [inline]

Returns the ownership of underlying O/S socket.

Returns:
TRUE, if the socket object has the ownership of underlying O/S socket.

Definition at line 246 of file OSRTSocket.h.

OSRTSOCKET OSRTSocket::getSocket (  )  const [inline]

This method returns the handle of the socket.

Returns:
The handle of the socket.

Definition at line 253 of file OSRTSocket.h.

int OSRTSocket::getStatus (  )  [inline]

Returns a completion status of last operation.

Returns:
Completion status of last operation:
  • 0 = success,
  • negative return value is error.

Definition at line 262 of file OSRTSocket.h.

EXTRTMETHOD int OSRTSocket::listen ( int  maxConnections  ) 

This method places a socket into a state where it is listening for an incoming connection.

Parameters:
maxConnections Maximum length of the queue of pending connections.
Returns:
Completion status of operation:
  • 0 = success,
  • negative return value is error.
See also:
rtxSocketListen
EXTRTMETHOD int OSRTSocket::recv ( OSOCTET *  pbuf,
size_t  bufsize 
)

This method receives data from a connected socket.

It is used to read incoming data on sockets. The socket must be connected before calling this function.

Parameters:
pbuf Pointer to the buffer for the incoming data.
bufsize Length of the buffer.
Returns:
If no error occurs, returns the number of bytes received. Negative error code if error occurred.
See also:
rtxSocketRecv
EXTRTMETHOD int OSRTSocket::send ( const OSOCTET *  pdata,
size_t  size 
)

This method sends data on a connected socket.

It is used to write outgoing data on a connected socket.

Parameters:
pdata Buffer containing the data to be transmitted.
size Length of the data in pdata.
Returns:
Completion status of operation:
  • 0 = success,
  • negative return value is error.
See also:
rtxSocketSend
void OSRTSocket::setOwnership ( OSBOOL  ownership  )  [inline]

Transfers an ownership of the underlying O/S socket to or from the socket object.

If the socket object has the ownership of the underlying O/S socket it will close the O/S socket when the socket object is being closed or destroyed.

Parameters:
ownership TRUE, if socket object should have ownership of the underlying O/S socket; FALSE, otherwise.

Definition at line 301 of file OSRTSocket.h.

static EXTRTMETHOD OSIPADDR OSRTSocket::stringToAddr ( const char *  pAddrStr  )  [static]

This method converts a string containing an Internet Protocol dotted address into a proper OSIPADDR address.

Parameters:
pAddrStr Null-terminated character string representing a number expressed in the Internet standard "." (dotted) notation.
Returns:
If no error occurs, returns OSIPADDR. OSIPADDR_INVALID, if error occurred.

The documentation for this class was generated from the following file: