head 1.4; access; symbols; locks; strict; comment @# @; 1.4 date 2002.09.07.01.50.36; author curt; state Exp; branches; next 1.3; 1.3 date 2002.08.31.19.01.51; author curt; state Exp; branches; next 1.2; 1.2 date 2002.08.31.18.53.59; author curt; state Exp; branches; next 1.1; 1.1 date 2002.02.15.17.21.55; author curt; state Exp; branches; next ; desc @@ 1.4 log @Updated doxygen docs. @ text @
Main Page Class Hierarchy Compound List File List Compound Members File Members

# SGSocket Class Reference

A socket I/O class based on SGIOChannel. More...

`#include <sg_socket.hxx>`

Inheritance diagram for SGSocket:

List of all members.

## Public Methods
| SGSocket (const string &host, const string &port, const string &style)
| Create an instance of SGSocket.
| ~SGSocket ()
| Destructor.
bool | open (const SGProtocolDir d)
| Open a channel.
int | read (char *buf, int length)
| The read() method is modeled after the read() Unix system call.
int | readline (char *buf, int length)
| The readline() method is similar to read() except that it will stop at the first end of line encountered in the input buffer.
int | write (const char *buf, const int length)
| The write() method is modeled after the write() Unix system call and is analogous to the read() method.
int | writestring (const char *str)
| The writestring() method is a simple wrapper that will calculate the length of a null terminated character array and write it to the output channel.
bool | close ()
| The close() method is modeled after the close() Unix system call and will close an open device.
bool | nonblock ()
| Enable non-blocking mode.
string | get_hostname () const
string | get_port_str () const

## Detailed Description

A socket I/O class based on SGIOChannel.

Definition at line 52 of file sg_socket.hxx.

## Constructor & Destructor Documentation

SGSocket::SGSocket | ( | const string & | host,
|  | const string & | port,
|  | const string & | style
| ) |

  | Create an instance of SGSocket. When calling the constructor you need to provide a host name, a port number, and a socket style. The convention used by the SGSocket class is that the server side listens and the client side sends. For a server socket, the host name should be empty. For a server, the port number is optional, if you do not specify a port, the system will assign one. For a client socket, you need to specify both a destination host and destination port. For both client and server sockets you must specify the socket type. Type must be either udp or tcp. Here's a quick breakdown of the major differences between UDP and TCP type sockets. TCP sockets are the type where you establish a connection and then can read and write to the socket from both ends. If one end of TCP socket connect quits, the other end will likely segfault if it doesn't take special precautions. But, the nice thing about TCP connections is that the underlying protocol guarantees that your message will get through. This imposes a certain performance overhead though on the communication because the protocol must resend failed messages. TCP sockets are good for sending periodic command/response type messages where performance isn't a big issues, but reliability is. UDP sockets on the other hand are a lower level protocol and don't have the same sort of connection as TCP sockets. With UDP sockets, the server end just sits and listens for incoming packets from anywhere. The client end sends it's message and forgets about it. It doesn't care if there isn't even a server out there listening and all the packets are getting lost. Although systems/networks usually do a pretty good job (statistically) of getting your UDP packets to their destination, there is no guarantee that any particular packet will make it. But, because of this low level implementation and lack of error checking, UDP packets are much faster and efficient. UDP packets are good for sending positional information to synchronize two applications. In this case, you want the information to arrive as quickly as possible, and if you lose a packet, you'd rather get new updated information rather than have the system waste time resending a packet that is becoming older and older with every retry. Parameters:
  host | name of host if direction is SG_IO_OUT or SG_IO_BI
  port | port number if we care to choose one.
  style | specify "udp" or "tcp"
Definition at line 37 of file sg_socket.cxx. References SG_LOG.

## Member Function Documentation

bool SGSocket::close | ( |  | ) | `[virtual]`

| The close() method is modeled after the close() Unix system call and will close an open device. You should call this method when you are done using your IO class, before it is destructed. Returns: result of close Reimplemented from SGIOChannel. Definition at line 349 of file sg_socket.cxx. Referenced by ~SGSocket().

string SGSocket::get_hostname | ( |  | ) | const`[inline]`

| Returns: the remote host name Definition at line 160 of file sg_socket.hxx.

string SGSocket::get_port_str | ( |  | ) | const`[inline]`

| Returns: the port number (in string form) Definition at line 163 of file sg_socket.hxx.

bool SGSocket::nonblock | ( |  | ) |

| Enable non-blocking mode. Returns: success/failure Definition at line 361 of file sg_socket.cxx. Referenced by open().

bool SGSocket::open | ( | const SGProtocolDir | d | ) | `[virtual]`

  | Open a channel. Parameters:
  d | channel communication "direction" Direction can be one of: SG_IO_IN - data will be flowing into this object to the application. SG_IO_OUT - data will be flowing out of this object from the application. SG_IO_BI - data will be flowing in both directions. SG_IO_NONE - data will not be flowing in either direction. This is here for the sake of completeness.
Returns: result of open Reimplemented from SGIOChannel. Definition at line 120 of file sg_socket.cxx. References nonblock(), SG_LOG, and SGProtocolDir.

int SGSocket::read | ( | char * | buf,
|  | int | length
| ) | `[virtual]`

  | The read() method is modeled after the read() Unix system call. You must provide a pointer to a character buffer that has enough allocated space for your potential read. You can also specify the maximum number of bytes allowed for this particular read. The actual number of bytes read is returned. You are responsible to ensure that the size of buf is large enough to accomodate your input message Parameters:
  buf | a char pointer to your input buffer
  length | max number of bytes to read
Returns: number of bytes read Reimplemented from SGIOChannel. Definition at line 207 of file sg_socket.cxx. References SG_LOG.

int SGSocket::readline | ( | char * | buf,
|  | int | length
| ) | `[virtual]`

  | The readline() method is similar to read() except that it will stop at the first end of line encountered in the input buffer. Parameters:
  buf | a char pointer to your input buffer
  length | max number of bytes to read
Returns: number of bytes read Reimplemented from SGIOChannel. Definition at line 236 of file sg_socket.cxx. References SG_LOG.

int SGSocket::write | ( | const char * | buf,
|  | const int | length
| ) | `[virtual]`

  | The write() method is modeled after the write() Unix system call and is analogous to the read() method. You provide a pointer to a buffer of data, and then length of that data to be written out. The number of bytes written is returned. Parameters:
  buf | a char pointer to your output buffer
  length | number of bytes to write
Returns: number of bytes written Reimplemented from SGIOChannel. Definition at line 314 of file sg_socket.cxx. References SG_LOG. Referenced by writestring().

int SGSocket::writestring | ( | const char * | str | ) | `[virtual]`

  | The writestring() method is a simple wrapper that will calculate the length of a null terminated character array and write it to the output channel. Parameters:
  buf | a char pointer to your output buffer
Returns: number of bytes written Reimplemented from SGIOChannel. Definition at line 340 of file sg_socket.cxx. References write().

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

- sg_socket.hxx
- sg_socket.cxx

@ 1.3 log @Oops, try again. @ text @d516 1 a516 1