* @param length max number of bytes to read
*/
virtual int readline( char *buf, int length );
+
+
+ /**
+ * 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.
+ * @param buf a char pointer to your output buffer
+ * @param length number of bytes to write
+ */
virtual int write( const char *buf, const int length );
+
+ /**
+ * 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.
+ * @param buf a char pointer to your output buffer
+ */
virtual int writestring( const char *str );
+
+ /**
+ * 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.
+ */
virtual bool close();
inline void set_type( SGChannelType t ) { type = t; }
-// sg_file.hxx -- File I/O routines
-//
+/** \file sg_file.hxx
+ * File I/O routines.
+ */
+
// Written by Curtis Olson, started November 1999.
//
// Copyright (C) 1999 Curtis L. Olson - curt@flightgear.org
SG_USING_STD(string);
+/**
+ * A file I/O class based on SGIOChannel.
+ */
class SGFile : public SGIOChannel {
string file_name;
public:
+ /**
+ * Create an instance of SGFile.
+ * When calling the constructor you need to provide a file
+ * name. This file is not opened immediately, but instead will be
+ * opened when the open() method is called.
+ * @param file name of file to open
+ */
SGFile( const string& file );
+
+ /** Destructor */
~SGFile();
// open the file based on specified direction
// close file
bool close();
+ /** Return the name of the file being manipulated. */
inline string get_file_name() const { return file_name; }
};
-// sg_serial.hxx -- Serial I/O routines
-//
+/**
+ * \file sg_serial.hxx
+ * Serial I/O routines
+ */
+
// Written by Curtis Olson, started November 1999.
//
// Copyright (C) 1999 Curtis L. Olson - curt@flightgear.org
SG_USING_STD(string);
-
+/**
+ * A serial I/O class based on SGIOChannel.
+ */
class SGSerial : public SGIOChannel {
string device;
public:
+ /**
+ * Create an instance of SGSerial.
+ * This creates an instance of the SGSerial class. You need to
+ * provide the serial device name and desired baud rate. For Unix
+ * style systems, device names will be similar to
+ * ``/dev/ttyS0''. For DOS style systems you may want to use
+ * something similar to ``COM1:''. As with the SGFile class,
+ * device is not opened immediately, but instead will be opened
+ * when the open() method is called.
+ * @param device_name name of serial device
+ * @param baud_rate speed of communication
+ */
SGSerial( const string& device_name, const string& baud_rate );
+
+ /** Destructor */
~SGSerial();
// open the serial port based on specified direction
// close port
bool close();
+ /** Return the serial port device name */
inline string get_device() const { return device; }
+
+ /** Return the baud rate */
inline string get_baud() const { return baud; }
};
-// sg_socket.hxx -- Socket I/O routines
-//
+/**
+ * \file sg_socket.hxx
+ * Socket I/O routines.
+ */
+
// Written by Curtis Olson, started November 1999.
//
// Copyright (C) 1999 Curtis L. Olson - curt@flightgear.org
#define SG_MAX_SOCKET_QUEUE 32
+/**
+ * A socket I/O class based on SGIOChannel.
+ */
class SGSocket : public SGIOChannel {
public:
#if defined(_MSC_VER)
public:
+ /**
+ * 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.
+ * @param host name of host if direction is SG_IO_OUT or SG_IO_BI
+ * @param port port number if we care to choose one.
+ * @param style specify "udp" or "tcp"
+ */
SGSocket( const string& host, const string& port, const string& style );
+
+ /** Destructor */
~SGSocket();
// If specified as a server (in direction for now) open the master
// close file
bool close();
- // Enable non-blocking mode.
+ /** Enable non-blocking mode. */
bool nonblock();
+ /** Return the remote host name */
inline string get_hostname() const { return hostname; }
+
+ /** Return the port number (in string form) */
inline string get_port_str() const { return port_str; }
};
#endif // _SG_SOCKET_HXX
-
-
projects / simgear.git / commitdiff