From bf0d95145d8a49410b6ed5ea6c451ee916b9fc02 Mon Sep 17 00:00:00 2001 From: curt Date: Sat, 24 Mar 2001 14:21:06 +0000 Subject: [PATCH 1/1] Doxygen ... --- simgear/io/iochannel.hxx | 23 ++++++++++++++ simgear/io/sg_file.hxx | 19 ++++++++++-- simgear/io/sg_serial.hxx | 28 +++++++++++++++-- simgear/io/sg_socket.hxx | 66 +++++++++++++++++++++++++++++++++++++--- 4 files changed, 126 insertions(+), 10 deletions(-) diff --git a/simgear/io/iochannel.hxx b/simgear/io/iochannel.hxx index cd40b6bd..3b693214 100644 --- a/simgear/io/iochannel.hxx +++ b/simgear/io/iochannel.hxx @@ -119,8 +119,31 @@ public: * @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; } diff --git a/simgear/io/sg_file.hxx b/simgear/io/sg_file.hxx index a0c35e6c..b116cf1f 100644 --- a/simgear/io/sg_file.hxx +++ b/simgear/io/sg_file.hxx @@ -1,5 +1,7 @@ -// 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 @@ -45,6 +47,9 @@ SG_USING_STD(string); +/** + * A file I/O class based on SGIOChannel. + */ class SGFile : public SGIOChannel { string file_name; @@ -52,7 +57,16 @@ class SGFile : public SGIOChannel { 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 @@ -73,6 +87,7 @@ public: // close file bool close(); + /** Return the name of the file being manipulated. */ inline string get_file_name() const { return file_name; } }; diff --git a/simgear/io/sg_serial.hxx b/simgear/io/sg_serial.hxx index 87c21877..e37fa722 100644 --- a/simgear/io/sg_serial.hxx +++ b/simgear/io/sg_serial.hxx @@ -1,5 +1,8 @@ -// 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 @@ -45,7 +48,9 @@ SG_USING_STD(string); - +/** + * A serial I/O class based on SGIOChannel. + */ class SGSerial : public SGIOChannel { string device; @@ -57,7 +62,21 @@ class SGSerial : public SGIOChannel { 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 @@ -78,7 +97,10 @@ public: // 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; } }; diff --git a/simgear/io/sg_socket.hxx b/simgear/io/sg_socket.hxx index 509ceca4..be817135 100644 --- a/simgear/io/sg_socket.hxx +++ b/simgear/io/sg_socket.hxx @@ -1,5 +1,8 @@ -// 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 @@ -45,6 +48,9 @@ SG_USING_STD(string); #define SG_MAX_SOCKET_QUEUE 32 +/** + * A socket I/O class based on SGIOChannel. + */ class SGSocket : public SGIOChannel { public: #if defined(_MSC_VER) @@ -89,7 +95,56 @@ private: 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 @@ -112,14 +167,15 @@ public: // 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 - - -- 2.39.5