]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/socket.h
Minor corrections
[wxWidgets.git] / interface / wx / socket.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: socket.h
3 // Purpose: interface of wxIPV4address
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxIPV4address
11
12
13 @library{wxbase}
14 @category{net}
15 */
16 class wxIPV4address : public wxIPaddress
17 {
18 public:
19 /**
20 Set address to any of the addresses of the current machine. Whenever
21 possible, use this function instead of LocalHost(),
22 as this correctly handles multi-homed hosts and avoids other small
23 problems. Internally, this is the same as setting the IP address
24 to @b INADDR_ANY.
25
26 @return Returns @true on success, @false if something went wrong.
27 */
28 bool AnyAddress();
29
30 //@{
31 /**
32 Returns the hostname which matches the IP address.
33 */
34 bool Hostname(const wxString& hostname);
35 Return value wxString Hostname();
36 //@}
37
38 /**
39 Returns a wxString containing the IP address in dot quad (127.0.0.1) format.
40 */
41 wxString IPAddress();
42
43 /**
44 Set address to localhost (127.0.0.1). Whenever possible, use the
45 AnyAddress(),
46 function instead of this one, as this will correctly handle multi-homed
47 hosts and avoid other small problems.
48 */
49 bool LocalHost();
50
51 //@{
52 /**
53 Returns the current service.
54 */
55 bool Service(const wxString& service);
56 Return value bool Service(unsigned short service);
57 Return value unsigned short Service();
58 //@}
59 };
60
61
62
63 /**
64 @class wxSocketServer
65
66
67 @library{wxnet}
68 @category{net}
69
70 @see wxSocketServer::WaitForAccept, wxSocketBase::SetNotify,
71 wxSocketBase::Notify, wxSocketServer::AcceptWith
72 */
73 class wxSocketServer : public wxSocketBase
74 {
75 public:
76 /**
77 Constructs a new server and tries to bind to the specified @e address.
78 Before trying to accept new connections, test whether it succeeded with
79 @ref wxSocketBase::isok wxSocketBase:IsOk.
80
81 @param address
82 Specifies the local address for the server (e.g. port number).
83 @param flags
84 Socket flags (See wxSocketBase::SetFlags)
85 */
86 wxSocketServer(const wxSockAddress& address,
87 wxSocketFlags flags = wxSOCKET_NONE);
88
89 /**
90 Destructor (it doesn't close the accepted connections).
91 */
92 ~wxSocketServer();
93
94 /**
95 Accepts an incoming connection request, and creates a new
96 wxSocketBase object which represents
97 the server-side of the connection.
98 If @a wait is @true and there are no pending connections to be
99 accepted, it will wait for the next incoming connection to
100 arrive. @b Warning: This will block the GUI.
101 If @a wait is @false, it will try to accept a pending connection
102 if there is one, but it will always return immediately without blocking
103 the GUI. If you want to use Accept in this way, you can either check for
104 incoming connections with WaitForAccept()
105 or catch @b wxSOCKET_CONNECTION events, then call Accept once you know
106 that there is an incoming connection waiting to be accepted.
107
108 @return Returns an opened socket connection, or @NULL if an error
109 occurred or if the wait parameter was @false and there
110 were no pending connections.
111
112 @see WaitForAccept(), wxSocketBase::SetNotify,
113 wxSocketBase::Notify, AcceptWith()
114 */
115 wxSocketBase* Accept(bool wait = true);
116
117 /**
118 Accept an incoming connection using the specified socket object.
119
120 @param socket
121 Socket to be initialized
122
123 @return Returns @true on success, or @false if an error occurred or if the
124 wait parameter was @false and there were no pending
125 connections.
126 */
127 bool AcceptWith(wxSocketBase& socket, bool wait = true);
128
129 /**
130 This function waits for an incoming connection. Use it if you want to call
131 Accept() or AcceptWith()
132 with @e wait set to @false, to detect when an incoming connection is waiting
133 to be accepted.
134
135 @param seconds
136 Number of seconds to wait.
137 If -1, it will wait for the default timeout,
138 as set with SetTimeout.
139 @param millisecond
140 Number of milliseconds to wait.
141
142 @return Returns @true if an incoming connection arrived, @false if the
143 timeout elapsed.
144 */
145 bool WaitForAccept(long seconds = -1, long millisecond = 0);
146 };
147
148
149
150 /**
151 @class wxIPaddress
152
153 wxIPaddress is an abstract base class for all internet protocol address
154 objects. Currently, only wxIPV4address
155 is implemented. An experimental implementation for IPV6, wxIPV6address,
156 is being developed.
157
158 @library{wxbase}
159 @category{net}
160 */
161 class wxIPaddress : public wxSockAddress
162 {
163 public:
164 /**
165 Internally, this is the same as setting the IP address
166 to @b INADDR_ANY.
167 On IPV4 implementations, 0.0.0.0
168 On IPV6 implementations, ::
169
170 @return Returns @true on success, @false if something went wrong.
171 */
172 virtual bool AnyAddress();
173
174 /**
175 Internally, this is the same as setting the IP address
176 to @b INADDR_BROADCAST.
177 On IPV4 implementations, 255.255.255.255
178
179 @return Returns @true on success, @false if something went wrong.
180 */
181 virtual bool BroadcastAddress();
182
183 //@{
184 /**
185 Returns the hostname which matches the IP address.
186 */
187 virtual bool Hostname(const wxString& hostname);
188 Return value virtual wxString Hostname();
189 //@}
190
191 /**
192 Returns a wxString containing the IP address.
193 */
194 virtual wxString IPAddress();
195
196 /**
197 Determines if current address is set to localhost.
198 */
199 virtual bool IsLocalHost();
200
201 /**
202 Set address to localhost.
203 On IPV4 implementations, 127.0.0.1
204 On IPV6 implementations, ::1
205
206 @return Returns @true on success, @false if something went wrong.
207 */
208 virtual bool LocalHost();
209
210 //@{
211 /**
212 Returns the current service.
213 */
214 virtual bool Service(const wxString& service);
215 Return value virtual bool Service(unsigned short service);
216 Return value virtual unsigned short Service();
217 //@}
218 };
219
220
221
222 /**
223 @class wxSocketClient
224
225
226 @library{wxnet}
227 @category{net}
228
229 @see wxSocketClient::WaitOnConnect, wxSocketBase::SetNotify,
230 wxSocketBase::Notify
231 */
232 class wxSocketClient : public wxSocketBase
233 {
234 public:
235 /**
236 Constructor.
237
238 @param flags
239 Socket flags (See wxSocketBase::SetFlags)
240 */
241 wxSocketClient(wxSocketFlags flags = wxSOCKET_NONE);
242
243 /**
244 Destructor. Please see wxSocketBase::Destroy.
245 */
246 ~wxSocketClient();
247
248 //@{
249 /**
250 Connects to a server using the specified address.
251 If @a wait is @true, Connect will wait until the connection
252 completes. @b Warning: This will block the GUI.
253 If @a wait is @false, Connect will try to establish the connection and
254 return immediately, without blocking the GUI. When used this way, even if
255 Connect returns @false, the connection request can be completed later.
256 To detect this, use WaitOnConnect(),
257 or catch @b wxSOCKET_CONNECTION events (for successful establishment)
258 and @b wxSOCKET_LOST events (for connection failure).
259
260 @param address
261 Address of the server.
262 @param local
263 Bind to the specified local address and port before connecting.
264 The local address and port can also be set using SetLocal,
265 and then using the 2-parameter Connect method.
266 @param wait
267 If @true, waits for the connection to complete.
268
269 @return Returns @true if the connection is established and no error
270 occurs.
271
272 @see WaitOnConnect(), wxSocketBase::SetNotify,
273 wxSocketBase::Notify
274 */
275 bool Connect(const wxSockAddress& address, bool wait = true);
276 bool Connect(const wxSockAddress& address, const wxSockAddress& local,
277 bool wait = true);
278 //@}
279
280 /**
281 Wait until a connection request completes, or until the specified timeout
282 elapses. Use this function after issuing a call
283 to Connect() with @e wait set to @false.
284
285 @param seconds
286 Number of seconds to wait.
287 If -1, it will wait for the default timeout,
288 as set with SetTimeout.
289 @param millisecond
290 Number of milliseconds to wait.
291
292 @return WaitOnConnect returns @true if the connection request completes.
293 This does not necessarily mean that the connection was
294 successfully established; it might also happen that the
295 connection was refused by the peer. Use IsConnected to
296 distinguish between these two situations.
297 */
298 bool WaitOnConnect(long seconds = -1, long milliseconds = 0);
299 };
300
301
302
303 /**
304 @class wxSockAddress
305
306 You are unlikely to need to use this class: only wxSocketBase uses it.
307
308 @library{wxbase}
309 @category{FIXME}
310
311 @see wxSocketBase, wxIPaddress, wxIPV4address
312 */
313 class wxSockAddress : public wxObject
314 {
315 public:
316 /**
317 Default constructor.
318 */
319 wxSockAddress();
320
321 /**
322 Default destructor.
323 */
324 ~wxSockAddress();
325
326 /**
327 Delete all informations about the address.
328 */
329 void Clear();
330
331 /**
332 Returns the length of the socket address.
333 */
334 int SockAddrLen();
335 };
336
337
338
339 /**
340 @class wxSocketEvent
341
342 This event class contains information about socket events.
343
344 @library{wxnet}
345 @category{net}
346
347 @see wxSocketBase, wxSocketClient, wxSocketServer
348 */
349 class wxSocketEvent : public wxEvent
350 {
351 public:
352 /**
353 Constructor.
354 */
355 wxSocketEvent(int id = 0);
356
357 /**
358 Gets the client data of the socket which generated this event, as
359 set with wxSocketBase::SetClientData.
360 */
361 void* GetClientData();
362
363 /**
364 Returns the socket object to which this event refers to. This makes
365 it possible to use the same event handler for different sockets.
366 */
367 wxSocketBase* GetSocket() const;
368
369 /**
370 Returns the socket event type.
371 */
372 wxSocketNotify GetSocketEvent() const;
373 };
374
375
376
377 /**
378 @class wxSocketBase
379
380 wxSocketBase is the base class for all socket-related objects, and it
381 defines all basic IO functionality.
382
383 Note: (Workaround for implementation limitation for wxWidgets up to 2.5.x)
384 If you want to use sockets or derived classes such as wxFTP in a secondary
385 thread,
386 call wxSocketBase::Initialize() (undocumented) from the main thread before
387 creating
388 any sockets - in wxApp::OnInit for example.
389 See http://wiki.wxwidgets.org/wiki.pl?WxSocket or
390 http://www.litwindow.com/knowhow/knowhow.html for more details.
391
392 @library{wxnet}
393 @category{net}
394
395 @see wxSocketEvent, wxSocketClient, wxSocketServer, @ref overview_samplesockets
396 "Sockets sample"
397 */
398 class wxSocketBase : public wxObject
399 {
400 public:
401 /**
402 Default constructor. Don't use it directly; instead, use
403 wxSocketClient to construct a socket client, or
404 wxSocketServer to construct a socket server.
405 */
406 wxSocketBase();
407
408 /**
409 Destructor. Do not destroy a socket using the delete operator directly;
410 use Destroy() instead. Also, do not create
411 socket objects in the stack.
412 */
413 ~wxSocketBase();
414
415 /**
416 Functions that perform basic IO functionality.
417 Close()
418
419 Discard()
420
421 Peek()
422
423 Read()
424
425 ReadMsg()
426
427 Unread()
428
429 Write()
430
431 WriteMsg()
432 Functions that perform a timed wait on a certain IO condition.
433 InterruptWait()
434
435 Wait()
436
437 WaitForLost()
438
439 WaitForRead()
440
441 WaitForWrite()
442
443 and also:
444 wxSocketServer::WaitForAccept
445
446 wxSocketClient::WaitOnConnect
447 Functions that allow applications to customize socket IO as needed.
448 GetFlags()
449
450 SetFlags()
451
452 SetTimeout()
453
454 SetLocal()
455 */
456
457
458 /**
459 This function shuts down the socket, disabling further transmission and
460 reception of data; it also disables events for the socket and frees the
461 associated system resources. Upon socket destruction, Close is automatically
462 called, so in most cases you won't need to do it yourself, unless you
463 explicitly want to shut down the socket, typically to notify the peer
464 that you are closing the connection.
465 */
466 void Close();
467
468 /**
469 @ref construct() wxSocketBase
470
471 @ref destruct() ~wxSocketBase
472
473 Destroy()
474 */
475
476
477 /**
478 Destroys the socket safely. Use this function instead of the delete operator,
479 since otherwise socket events could reach the application even after the
480 socket has been destroyed. To prevent this problem, this function appends
481 the wxSocket to a list of object to be deleted on idle time, after all
482 events have been processed. For the same reason, you should avoid creating
483 socket objects in the stack.
484 Destroy calls Close() automatically.
485
486 @return Always @true.
487 */
488 bool Destroy();
489
490 /**
491 This function simply deletes all bytes in the incoming queue. This function
492 always returns immediately and its operation is not affected by IO flags.
493 Use LastCount() to verify the number of bytes actually discarded.
494 If you use Error(), it will always return @false.
495 */
496 wxSocketBase Discard();
497
498 /**
499 Returns @true if an error occurred in the last IO operation.
500 Use this function to check for an error condition after one of the
501 following calls: Discard, Peek, Read, ReadMsg, Unread, Write, WriteMsg.
502 */
503 bool Error() const;
504
505 /**
506 Returns a pointer of the client data for this socket, as set with
507 SetClientData()
508 */
509 void* GetClientData() const;
510
511 /**
512 Returns current IO flags, as set with SetFlags()
513 */
514 wxSocketFlags GetFlags() const;
515
516 /**
517 This function returns the local address field of the socket. The local
518 address field contains the complete local address of the socket (local
519 address, local port, ...).
520
521 @return @true if no error happened, @false otherwise.
522 */
523 bool GetLocal(wxSockAddress& addr) const;
524
525 /**
526 This function returns the peer address field of the socket. The peer
527 address field contains the complete peer host address of the socket
528 (address, port, ...).
529
530 @return @true if no error happened, @false otherwise.
531 */
532 bool GetPeer(wxSockAddress& addr) const;
533
534 /**
535 Functions that allow applications to receive socket events.
536 Notify()
537
538 SetNotify()
539
540 GetClientData()
541
542 SetClientData()
543
544 SetEventHandler()
545 */
546
547
548 /**
549 Use this function to interrupt any wait operation currently in progress.
550 Note that this is not intended as a regular way to interrupt a Wait call,
551 but only as an escape mechanism for exceptional situations where it is
552 absolutely necessary to use it, for example to abort an operation due to
553 some exception or abnormal problem. InterruptWait is automatically called
554 when you Close() a socket (and thus also upon
555 socket destruction), so you don't need to use it in these cases.
556 Wait(),
557 wxSocketServer::WaitForAccept,
558 WaitForLost(),
559 WaitForRead(),
560 WaitForWrite(),
561 wxSocketClient::WaitOnConnect
562 */
563 void InterruptWait();
564
565 /**
566 Returns @true if the socket is connected.
567 */
568 bool IsConnected() const;
569
570 /**
571 This function waits until the socket is readable. This might mean that
572 queued data is available for reading or, for streamed sockets, that
573 the connection has been closed, so that a read operation will complete
574 immediately without blocking (unless the @b wxSOCKET_WAITALL flag
575 is set, in which case the operation might still block).
576 */
577 bool IsData() const;
578
579 /**
580 Returns @true if the socket is not connected.
581 */
582 bool IsDisconnected() const;
583
584 /**
585 Returns @true if the socket is initialized and ready and @false in other
586 cases.
587 */
588 bool IsOk() const;
589
590 /**
591 Returns the number of bytes read or written by the last IO call.
592 Use this function to get the number of bytes actually transferred
593 after using one of the following IO calls: Discard, Peek, Read,
594 ReadMsg, Unread, Write, WriteMsg.
595 */
596 wxUint32 LastCount() const;
597
598 /**
599 Returns the last wxSocket error. See @ref overview_wxsocketbase "wxSocket
600 errors".
601 Please note that this function merely returns the last error code,
602 but it should not be used to determine if an error has occurred (this
603 is because successful operations do not change the LastError value).
604 Use Error() first, in order to determine
605 if the last IO call failed. If this returns @true, use LastError
606 to discover the cause of the error.
607 */
608 wxSocketError LastError() const;
609
610 /**
611 According to the @a notify value, this function enables
612 or disables socket events. If @a notify is @true, the events
613 configured with SetNotify() will
614 be sent to the application. If @a notify is @false; no events
615 will be sent.
616 */
617 void Notify(bool notify);
618
619 /**
620 This function peeks a buffer of @a nbytes bytes from the socket.
621 Peeking a buffer doesn't delete it from the socket input queue.
622 Use LastCount() to verify the number of bytes actually peeked.
623 Use Error() to determine if the operation succeeded.
624
625 @param buffer
626 Buffer where to put peeked data.
627 @param nbytes
628 Number of bytes.
629
630 @return Returns a reference to the current object.
631
632 @see Error(), LastError(), LastCount(),
633 SetFlags()
634 */
635 wxSocketBase Peek(void* buffer, wxUint32 nbytes);
636
637 /**
638 This function reads a buffer of @a nbytes bytes from the socket.
639 Use LastCount() to verify the number of bytes actually read.
640 Use Error() to determine if the operation succeeded.
641
642 @param buffer
643 Buffer where to put read data.
644 @param nbytes
645 Number of bytes.
646
647 @return Returns a reference to the current object.
648
649 @see Error(), LastError(), LastCount(),
650 SetFlags()
651 */
652 wxSocketBase Read(void* buffer, wxUint32 nbytes);
653
654 /**
655 This function reads a buffer sent by WriteMsg()
656 on a socket. If the buffer passed to the function isn't big enough, the
657 remaining bytes will be discarded. This function always waits for the
658 buffer to be entirely filled, unless an error occurs.
659 Use LastCount() to verify the number of bytes actually read.
660 Use Error() to determine if the operation succeeded.
661
662 @param buffer
663 Buffer where to put read data.
664 @param nbytes
665 Size of the buffer.
666
667 @return Returns a reference to the current object.
668
669 @see Error(), LastError(), LastCount(),
670 SetFlags(), WriteMsg()
671 */
672 wxSocketBase ReadMsg(void* buffer, wxUint32 nbytes);
673
674 /**
675 This function restores the previous state of the socket, as saved
676 with SaveState()
677 Calls to SaveState and RestoreState can be nested.
678
679 @see SaveState()
680 */
681 void RestoreState();
682
683 /**
684 This function saves the current state of the socket in a stack. Socket
685 state includes flags, as set with SetFlags(),
686 event mask, as set with SetNotify() and
687 Notify(), user data, as set with
688 SetClientData().
689 Calls to SaveState and RestoreState can be nested.
690
691 @see RestoreState()
692 */
693 void SaveState();
694
695 /**
696 Sets user-supplied client data for this socket. All socket events will
697 contain a pointer to this data, which can be retrieved with
698 the wxSocketEvent::GetClientData function.
699 */
700 void SetClientData(void* data);
701
702 /**
703 Sets an event handler to be called when a socket event occurs. The
704 handler will be called for those events for which notification is
705 enabled with SetNotify() and
706 Notify().
707
708 @param handler
709 Specifies the event handler you want to use.
710 @param id
711 The id of socket event.
712
713 @see SetNotify(), Notify(), wxSocketEvent, wxEvtHandler
714 */
715 void SetEventHandler(wxEvtHandler& handler, int id = -1);
716
717 /**
718 Use SetFlags to customize IO operation for this socket.
719 The @a flags parameter may be a combination of flags ORed together.
720 The following flags can be used:
721
722 @b wxSOCKET_NONE
723
724 Normal functionality.
725
726 @b wxSOCKET_NOWAIT
727
728 Read/write as much data as possible and return immediately.
729
730 @b wxSOCKET_WAITALL
731
732 Wait for all required data to be read/written unless an error occurs.
733
734 @b wxSOCKET_BLOCK
735
736 Block the GUI (do not yield) while reading/writing data.
737
738 @b wxSOCKET_REUSEADDR
739
740 Allows the use of an in-use port (wxServerSocket only)
741
742 @b wxSOCKET_BROADCAST
743
744 Switches the socket to broadcast mode
745
746 @b wxSOCKET_NOBIND
747
748 Stops the socket from being bound to a specific adapter (normally used in
749 conjunction with @b wxSOCKET_BROADCAST)
750
751 A brief overview on how to use these flags follows.
752 If no flag is specified (this is the same as @b wxSOCKET_NONE),
753 IO calls will return after some data has been read or written, even
754 when the transfer might not be complete. This is the same as issuing
755 exactly one blocking low-level call to recv() or send(). Note
756 that @e blocking here refers to when the function returns, not
757 to whether the GUI blocks during this time.
758 If @b wxSOCKET_NOWAIT is specified, IO calls will return immediately.
759 Read operations will retrieve only available data. Write operations will
760 write as much data as possible, depending on how much space is available
761 in the output buffer. This is the same as issuing exactly one nonblocking
762 low-level call to recv() or send(). Note that @e nonblocking here
763 refers to when the function returns, not to whether the GUI blocks during
764 this time.
765 If @b wxSOCKET_WAITALL is specified, IO calls won't return until ALL
766 the data has been read or written (or until an error occurs), blocking if
767 necessary, and issuing several low level calls if necessary. This is the
768 same as having a loop which makes as many blocking low-level calls to
769 recv() or send() as needed so as to transfer all the data. Note
770 that @e blocking here refers to when the function returns, not
771 to whether the GUI blocks during this time.
772 The @b wxSOCKET_BLOCK flag controls whether the GUI blocks during
773 IO operations. If this flag is specified, the socket will not yield
774 during IO calls, so the GUI will remain blocked until the operation
775 completes. If it is not used, then the application must take extra
776 care to avoid unwanted reentrance.
777 The @b wxSOCKET_REUSEADDR flag controls the use of the SO_REUSEADDR standard
778 setsockopt() flag. This flag allows the socket to bind to a port that is
779 already in use.
780 This is mostly used on UNIX-based systems to allow rapid starting and stopping
781 of a server -
782 otherwise you may have to wait several minutes for the port to become available.
783 wxSOCKET_REUSEADDR can also be used with socket clients to (re)bind to a
784 particular local port
785 for an outgoing connection.
786 This option can have surprising platform dependent behavior, so check the
787 documentation for
788 your platform's implementation of setsockopt(). Note that on BSD-based systems
789 (e.g. Mac OS X),
790 use of wxSOCKET_REUSEADDR implies SO_REUSEPORT in addition to SO_REUSEADDR to
791 be consistent
792 with Windows.
793 The @b wxSOCKET_BROADCAST flag controls the use of the SO_BROADCAST standard
794 setsockopt() flag. This flag allows the socket to use the broadcast address,
795 and is generally
796 used in conjunction with @b wxSOCKET_NOBIND and wxIPaddress::BroadcastAddress.
797 So:
798 @b wxSOCKET_NONE will try to read at least SOME data, no matter how much.
799 @b wxSOCKET_NOWAIT will always return immediately, even if it cannot
800 read or write ANY data.
801 @b wxSOCKET_WAITALL will only return when it has read or written ALL
802 the data.
803 @b wxSOCKET_BLOCK has nothing to do with the previous flags and
804 it controls whether the GUI blocks.
805 @b wxSOCKET_REUSEADDR controls special platform-specific behavior for
806 reusing local addresses/ports.
807 */
808 void SetFlags(wxSocketFlags flags);
809
810 /**
811 This function allows you to set the local address and port,
812 useful when an application needs to reuse a particular port. When
813 a local port is set for a wxSocketClient,
814 @b bind will be called before @b connect.
815 */
816 bool SetLocal(const wxIPV4address& local);
817
818 /**
819 SetNotify specifies which socket events are to be sent to the event handler.
820 The @a flags parameter may be combination of flags ORed together. The
821 following flags can be used:
822
823 @b wxSOCKET_INPUT_FLAG
824
825 to receive wxSOCKET_INPUT
826
827 @b wxSOCKET_OUTPUT_FLAG
828
829 to receive wxSOCKET_OUTPUT
830
831 @b wxSOCKET_CONNECTION_FLAG
832
833 to receive wxSOCKET_CONNECTION
834
835 @b wxSOCKET_LOST_FLAG
836
837 to receive wxSOCKET_LOST
838
839 For example:
840
841 In this example, the user will be notified about incoming socket data and
842 whenever the connection is closed.
843 For more information on socket events see @ref overview_wxsocketbase "wxSocket
844 events".
845 */
846 void SetNotify(wxSocketEventFlags flags);
847
848 /**
849 This function sets the default socket timeout in seconds. This timeout
850 applies to all IO calls, and also to the Wait() family
851 of functions if you don't specify a wait interval. Initially, the default
852 timeout is 10 minutes.
853 */
854 void SetTimeout(int seconds);
855
856 /**
857 Functions to retrieve current state and miscellaneous info.
858 Error()
859
860 GetLocal()
861
862 GetPeer()
863 IsConnected()
864
865 IsData()
866
867 IsDisconnected()
868
869 LastCount()
870
871 LastError()
872
873 IsOk()
874
875 SaveState()
876
877 RestoreState()
878 */
879
880
881 /**
882 This function unreads a buffer. That is, the data in the buffer is put back
883 in the incoming queue. This function is not affected by wxSocket flags.
884 If you use LastCount(), it will always return @e nbytes.
885 If you use Error(), it will always return @false.
886
887 @param buffer
888 Buffer to be unread.
889 @param nbytes
890 Number of bytes.
891
892 @return Returns a reference to the current object.
893
894 @see Error(), LastCount(), LastError()
895 */
896 wxSocketBase Unread(const void* buffer, wxUint32 nbytes);
897
898 /**
899 This function waits until any of the following conditions is @true:
900
901 The socket becomes readable.
902 The socket becomes writable.
903 An ongoing connection request has completed (wxSocketClient only)
904 An incoming connection request has arrived (wxSocketServer only)
905 The connection has been closed.
906 Note that it is recommended to use the individual Wait functions
907 to wait for the required condition, instead of this one.
908
909 @param seconds
910 Number of seconds to wait.
911 If -1, it will wait for the default timeout,
912 as set with SetTimeout.
913 @param millisecond
914 Number of milliseconds to wait.
915
916 @return Returns @true when any of the above conditions is satisfied,
917 @false if the timeout was reached.
918
919 @see InterruptWait(), wxSocketServer::WaitForAccept,
920 WaitForLost(), WaitForRead(),
921 WaitForWrite(), wxSocketClient::WaitOnConnect
922 */
923 bool Wait(long seconds = -1, long millisecond = 0);
924
925 /**
926 This function waits until the connection is lost. This may happen if
927 the peer gracefully closes the connection or if the connection breaks.
928
929 @param seconds
930 Number of seconds to wait.
931 If -1, it will wait for the default timeout,
932 as set with SetTimeout.
933 @param millisecond
934 Number of milliseconds to wait.
935
936 @return Returns @true if the connection was lost, @false if the timeout
937 was reached.
938
939 @see InterruptWait(), Wait()
940 */
941 bool WaitForLost(long seconds = -1, long millisecond = 0);
942
943 /**
944 This function waits until the socket is readable. This might mean that
945 queued data is available for reading or, for streamed sockets, that
946 the connection has been closed, so that a read operation will complete
947 immediately without blocking (unless the @b wxSOCKET_WAITALL flag
948 is set, in which case the operation might still block).
949
950 @param seconds
951 Number of seconds to wait.
952 If -1, it will wait for the default timeout,
953 as set with SetTimeout.
954 @param millisecond
955 Number of milliseconds to wait.
956
957 @return Returns @true if the socket becomes readable, @false on timeout.
958
959 @see InterruptWait(), Wait()
960 */
961 bool WaitForRead(long seconds = -1, long millisecond = 0);
962
963 /**
964 This function waits until the socket becomes writable. This might mean that
965 the socket is ready to send new data, or for streamed sockets, that the
966 connection has been closed, so that a write operation is guaranteed to
967 complete immediately (unless the @b wxSOCKET_WAITALL flag is set,
968 in which case the operation might still block).
969
970 @param seconds
971 Number of seconds to wait.
972 If -1, it will wait for the default timeout,
973 as set with SetTimeout.
974 @param millisecond
975 Number of milliseconds to wait.
976
977 @return Returns @true if the socket becomes writable, @false on timeout.
978
979 @see InterruptWait(), Wait()
980 */
981 bool WaitForWrite(long seconds = -1, long millisecond = 0);
982
983 /**
984 This function writes a buffer of @a nbytes bytes to the socket.
985 Use LastCount() to verify the number of bytes actually written.
986 Use Error() to determine if the operation succeeded.
987
988 @param buffer
989 Buffer with the data to be sent.
990 @param nbytes
991 Number of bytes.
992
993 @return Returns a reference to the current object.
994
995 @see Error(), LastError(), LastCount(),
996 SetFlags()
997 */
998 wxSocketBase Write(const void* buffer, wxUint32 nbytes);
999
1000 /**
1001 This function writes a buffer of @a nbytes bytes from the socket, but it
1002 writes a short header before so that ReadMsg()
1003 knows how much data should it actually read. So, a buffer sent with WriteMsg
1004 @b must be read with ReadMsg. This function always waits for the entire
1005 buffer to be sent, unless an error occurs.
1006 Use LastCount() to verify the number of bytes actually written.
1007 Use Error() to determine if the operation succeeded.
1008
1009 @param buffer
1010 Buffer with the data to be sent.
1011 @param nbytes
1012 Number of bytes to send.
1013
1014 @return Returns a reference to the current object.
1015 */
1016 wxSocketBase WriteMsg(const void* buffer, wxUint32 nbytes);
1017 };
1018
1019
1020
1021 /**
1022 @class wxDatagramSocket
1023
1024
1025 @library{wxnet}
1026 @category{FIXME}
1027
1028 @see wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount,
1029 wxSocketBase::SetFlags,
1030 */
1031 class wxDatagramSocket : public wxSocketBase
1032 {
1033 public:
1034 /**
1035 Constructor.
1036
1037 @param flags
1038 Socket flags (See wxSocketBase::SetFlags)
1039 */
1040 wxDatagramSocket(wxSocketFlags flags = wxSOCKET_NONE);
1041
1042 /**
1043 Destructor. Please see wxSocketBase::Destroy.
1044 */
1045 ~wxDatagramSocket();
1046
1047 /**
1048 This function reads a buffer of @a nbytes bytes from the socket.
1049 Use wxSocketBase::LastCount to verify the number of bytes actually read.
1050 Use wxSocketBase::Error to determine if the operation succeeded.
1051
1052 @param address
1053 Any address - will be overwritten with the address of the peer that sent
1054 that data.
1055 @param buffer
1056 Buffer where to put read data.
1057 @param nbytes
1058 Number of bytes.
1059
1060 @return Returns a reference to the current object, and the address of
1061 the peer that sent the data on address param.
1062
1063 @see wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount,
1064 wxSocketBase::SetFlags,
1065 */
1066 wxDatagramSocket ReceiveFrom(wxSockAddress& address,
1067 void* buffer,
1068 wxUint32 nbytes);
1069
1070 /**
1071 This function writes a buffer of @a nbytes bytes to the socket.
1072 Use wxSocketBase::LastCount to verify the number of bytes actually wrote.
1073 Use wxSocketBase::Error to determine if the operation succeeded.
1074
1075 @param address
1076 The address of the destination peer for this data.
1077 @param buffer
1078 Buffer where read data is.
1079 @param nbytes
1080 Number of bytes.
1081
1082 @return Returns a reference to the current object.
1083 */
1084 wxDatagramSocket SendTo(const wxSockAddress& address,
1085 const void* buffer,
1086 wxUint32 nbytes);
1087 };
1088