Main MRPT website > C++ reference
MRPT logo
CClientTCPSocket.h
Go to the documentation of this file.
1 /* +---------------------------------------------------------------------------+
2  | The Mobile Robot Programming Toolkit (MRPT) C++ library |
3  | |
4  | http://www.mrpt.org/ |
5  | |
6  | Copyright (C) 2005-2012 University of Malaga |
7  | |
8  | This software was written by the Machine Perception and Intelligent |
9  | Robotics Lab, University of Malaga (Spain). |
10  | Contact: Jose-Luis Blanco <jlblanco@ctima.uma.es> |
11  | |
12  | This file is part of the MRPT project. |
13  | |
14  | MRPT is free software: you can redistribute it and/or modify |
15  | it under the terms of the GNU General Public License as published by |
16  | the Free Software Foundation, either version 3 of the License, or |
17  | (at your option) any later version. |
18  | |
19  | MRPT is distributed in the hope that it will be useful, |
20  | but WITHOUT ANY WARRANTY; without even the implied warranty of |
21  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
22  | GNU General Public License for more details. |
23  | |
24  | You should have received a copy of the GNU General Public License |
25  | along with MRPT. If not, see <http://www.gnu.org/licenses/>. |
26  | |
27  +---------------------------------------------------------------------------+ */
28 #ifndef CClientTCPSocket_H
29 #define CClientTCPSocket_H
30 
31 #include <mrpt/config.h>
32 #include <mrpt/utils/utils_defs.h>
33 #include <mrpt/system/os.h>
34 #include <mrpt/utils/CStream.h>
35 
36 namespace mrpt
37 {
38 namespace utils
39 {
40  class CServerTCPSocket;
41  class CMessage;
42 
43  /** \defgroup network_grp Networking, sockets, DNS
44  * \ingroup mrpt_base_grp */
45 
46  /** A TCP socket that can be connected to a TCP server, implementing MRPT's CStream interface for passing objects as well as generic read/write methods.
47  * Unless otherwise noticed, operations are blocking.
48  *
49  * Note that for convenience, DNS lookup is performed with a timeout (default=3000ms), which can be changed by the static member CClientTCPSocket::DNS_LOOKUP_TIMEOUT_MS
50  * \ingroup network_grp
51  */
52  class BASE_IMPEXP CClientTCPSocket : public CStream
53  {
54  friend class CServerTCPSocket;
55 
56  public:
57  /** See description of CClientTCPSocket */
58  static unsigned int DNS_LOOKUP_TIMEOUT_MS;
59 
60  protected:
61 
62 #ifdef MRPT_OS_WINDOWS
63  /** The handle for the connected TCP socket, or INVALID_SOCKET
64  */
65 # if MRPT_WORD_SIZE==64
66  uint64_t m_hSock;
67 # else
68  uint32_t m_hSock;
69 # endif
70 #else
71 
72  /** The handle for the connected TCP socket, or -1
73  */
74  int m_hSock;
75 #endif
76 
77  /** The IP address of the remote part of the connection.
78  */
79  std::string m_remotePartIP;
80 
81  /** The TCP port of the remote part of the connection.
82  */
83  unsigned short m_remotePartPort;
84 
85 
86  /** Introduces a virtual method responsible for reading from the stream (This method BLOCKS)
87  * This method is implemented as a call to "readAsync" with infinite timeouts.
88  * \sa readAsync
89  */
90  size_t Read(void *Buffer, size_t Count);
91 
92  /** Introduces a virtual method responsible for writing to the stream.
93  * Write attempts to write up to Count bytes to Buffer, and returns the number of bytes actually written.
94  * This method is implemented as a call to "writeAsync" with infinite timeouts.
95  * \sa writeAsync
96  */
97  size_t Write(const void *Buffer, size_t Count);
98 
99  /** Returns a description of the last error */
100  std::string getLastErrorStr();
101 
102  public:
103  /** Default constructor
104  * \sa connect
105  */
106  CClientTCPSocket( );
107 
108  /** Destructor
109  */
110  ~CClientTCPSocket( );
111 
112  /** Establishes a connection with a remote part.
113  * \param remotePartAddress This string can be a host name, like "server" or "www.mydomain.org", or an IP address "11.22.33.44".
114  * \param remotePartTCPPort The port on the remote machine to connect to.
115  * \param timeout_ms The timeout to wait for the connection (0: NO TIMEOUT)
116  * \exception This method raises an exception if an error is found with a textual description of the error.
117  */
118  void connect(
119  const std::string &remotePartAddress,
120  unsigned short remotePartTCPPort,
121  unsigned int timeout_ms = 0 );
122 
123  /** Returns true if this objects represents a successfully connected socket.
124  */
125  bool isConnected();
126 
127  /** Closes the connection.
128  */
129  void close();
130 
131  /** Writes a string to the socket.
132  * \exception std::exception On communication errors
133  */
134  void sendString( const std::string &str );
135 
136  /** This virtual method has no effect in this implementation over a TCP socket, and its use raises an exception
137  */
138  uint64_t Seek(long Offset, CStream::TSeekOrigin Origin = sFromBeginning)
139  {
140  MRPT_START
141  MRPT_UNUSED_PARAM(Offset); MRPT_UNUSED_PARAM(Origin);
142  THROW_EXCEPTION("This method has no effect in this class!");
143  MRPT_END
144  }
145 
146  /** This virtual method has no effect in this implementation over a TCP socket, and its use raises an exception
147  */
148  uint64_t getTotalBytesCount()
149  {
150  MRPT_START
151  THROW_EXCEPTION("This method has no effect in this class!");
152  MRPT_END
153  }
154 
155  /** This virtual method has no effect in this implementation over a TCP socket, and its use raises an exception
156  */
157  uint64_t getPosition()
158  {
159  MRPT_START
160  THROW_EXCEPTION("This method has no effect in this class!");
161  MRPT_END
162  }
163 
164  /** A method for reading from the socket with an optional timeout.
165  * \param Buffer The destination of data.
166  * \param Cound The number of bytes to read.
167  * \param timeoutStart_ms The maximum timeout (in milliseconds) to wait for the starting of data from the other side.
168  * \param timeoutBetween_ms The maximum timeout (in milliseconds) to wait for a chunk of data after a previous one.
169  * Set timeout's to -1 to block until the desired number of bytes are read, or an error happens.
170  * \return The number of actually read bytes.
171  */
172  size_t readAsync(
173  void *Buffer,
174  const size_t Count,
175  const int timeoutStart_ms = -1,
176  const int timeoutBetween_ms = -1);
177 
178  /** A method for writing to the socket with optional timeouts.
179  * The method supports writing block by block as the socket allows us to write more data.
180  * \param Buffer The data.
181  * \param Cound The number of bytes to write.
182  * \param timeout_ms The maximum timeout (in milliseconds) to wait for the socket to be available for writing (for each block).
183  * Set timeout's to -1 to block until the desired number of bytes are written, or an error happens.
184  * \return The number of actually written bytes.
185  */
186  size_t writeAsync(
187  const void *Buffer,
188  const size_t Count,
189  const int timeout_ms = -1 );
190 
191  /** Send a message through the TCP stream.
192  * \param outMsg The message to be shown.
193  * \param timeout_ms The maximum timeout (in milliseconds) to wait for the socket in each write operation.
194  * \return Returns false on any error, or true if everything goes fine.
195  */
196  bool sendMessage(
197  const CMessage& outMsg,
198  const int timeout_ms = -1
199  );
200 
201  /** Waits for an incoming message through the TCP stream.
202  * \param inMsg The received message is placed here.
203  * \param timeoutStart_ms The maximum timeout (in milliseconds) to wait for the starting of data from the other side.
204  * \param timeoutBetween_ms The maximum timeout (in milliseconds) to wait for a chunk of data after a previous one.
205  * \return Returns false on any error (or timeout), or true if everything goes fine.
206  */
207  bool receiveMessage(
208  CMessage& inMsg,
209  const unsigned int timeoutStart_ms = 100,
210  const unsigned int timeoutBetween_ms = 1000
211  );
212 
213  /** Return the number of bytes already in the receive queue (they can be read without waiting) */
214  size_t getReadPendingBytes();
215 
216  }; // End of class def.
217 
218  } // End of namespace
219 } // end of namespace
220 #endif


Page generated by Doxygen 1.8.3 for MRPT 0.9.6 SVN: at Fri Feb 15 22:05:02 EST 2013