X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/328f5751e8a06727b137189fe04891a9f43bfc8b..7ace5fd8e03c5b49d672e0363a8d4960bbf80592:/interface/socket.h diff --git a/interface/socket.h b/interface/socket.h index b95dafd1d5..2312cf26e0 100644 --- a/interface/socket.h +++ b/interface/socket.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: socket.h -// Purpose: documentation for wxIPV4address class +// Purpose: interface of wxIPV4address // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -23,8 +23,8 @@ public: as this correctly handles multi-homed hosts and avoids other small problems. Internally, this is the same as setting the IP address to @b INADDR_ANY. - - @returns Returns @true on success, @false if something went wrong. + + @return Returns @true on success, @false if something went wrong. */ bool AnyAddress(); @@ -60,6 +60,7 @@ public: }; + /** @class wxSocketServer @wxheader{socket.h} @@ -68,9 +69,8 @@ public: @library{wxnet} @category{net} - @seealso - wxSocketServer::WaitForAccept, wxSocketBase::SetNotify, wxSocketBase::Notify, - wxSocketServer::AcceptWith + @see wxSocketServer::WaitForAccept, wxSocketBase::SetNotify, + wxSocketBase::Notify, wxSocketServer::AcceptWith */ class wxSocketServer : public wxSocketBase { @@ -79,7 +79,7 @@ public: Constructs a new server and tries to bind to the specified @e address. Before trying to accept new connections, test whether it succeeded with @ref wxSocketBase::isok wxSocketBase:IsOk. - + @param address Specifies the local address for the server (e.g. port number). @param flags @@ -106,11 +106,11 @@ public: incoming connections with WaitForAccept() or catch @b wxSOCKET_CONNECTION events, then call Accept once you know that there is an incoming connection waiting to be accepted. - - @returns Returns an opened socket connection, or @NULL if an error + + @return Returns an opened socket connection, or @NULL if an error occurred or if the wait parameter was @false and there were no pending connections. - + @see WaitForAccept(), wxSocketBase::SetNotify, wxSocketBase::Notify, AcceptWith() */ @@ -118,11 +118,11 @@ public: /** Accept an incoming connection using the specified socket object. - + @param socket Socket to be initialized - - @returns Returns @true on success, or @false if an error occurred or if the + + @return Returns @true on success, or @false if an error occurred or if the wait parameter was @false and there were no pending connections. */ @@ -133,21 +133,22 @@ public: Accept() or AcceptWith() with @e wait set to @false, to detect when an incoming connection is waiting to be accepted. - + @param seconds Number of seconds to wait. If -1, it will wait for the default timeout, as set with SetTimeout. @param millisecond Number of milliseconds to wait. - - @returns Returns @true if an incoming connection arrived, @false if the + + @return Returns @true if an incoming connection arrived, @false if the timeout elapsed. */ bool WaitForAccept(long seconds = -1, long millisecond = 0); }; + /** @class wxIPaddress @wxheader{socket.h} @@ -168,8 +169,8 @@ public: to @b INADDR_ANY. On IPV4 implementations, 0.0.0.0 On IPV6 implementations, :: - - @returns Returns @true on success, @false if something went wrong. + + @return Returns @true on success, @false if something went wrong. */ virtual bool AnyAddress(); @@ -177,8 +178,8 @@ public: Internally, this is the same as setting the IP address to @b INADDR_BROADCAST. On IPV4 implementations, 255.255.255.255 - - @returns Returns @true on success, @false if something went wrong. + + @return Returns @true on success, @false if something went wrong. */ virtual bool BroadcastAddress(); @@ -204,8 +205,8 @@ public: Set address to localhost. On IPV4 implementations, 127.0.0.1 On IPV6 implementations, ::1 - - @returns Returns @true on success, @false if something went wrong. + + @return Returns @true on success, @false if something went wrong. */ virtual bool LocalHost(); @@ -220,6 +221,7 @@ public: }; + /** @class wxSocketClient @wxheader{socket.h} @@ -228,15 +230,15 @@ public: @library{wxnet} @category{net} - @seealso - wxSocketClient::WaitOnConnect, wxSocketBase::SetNotify, wxSocketBase::Notify + @see wxSocketClient::WaitOnConnect, wxSocketBase::SetNotify, + wxSocketBase::Notify */ class wxSocketClient : public wxSocketBase { public: /** Constructor. - + @param flags Socket flags (See wxSocketBase::SetFlags) */ @@ -258,7 +260,7 @@ public: To detect this, use WaitOnConnect(), or catch @b wxSOCKET_CONNECTION events (for successful establishment) and @b wxSOCKET_LOST events (for connection failure). - + @param address Address of the server. @param local @@ -267,10 +269,10 @@ public: and then using the 2-parameter Connect method. @param wait If @true, waits for the connection to complete. - - @returns Returns @true if the connection is established and no error + + @return Returns @true if the connection is established and no error occurs. - + @see WaitOnConnect(), wxSocketBase::SetNotify, wxSocketBase::Notify */ @@ -283,15 +285,15 @@ public: Wait until a connection request completes, or until the specified timeout elapses. Use this function after issuing a call to Connect() with @e wait set to @false. - + @param seconds Number of seconds to wait. If -1, it will wait for the default timeout, as set with SetTimeout. @param millisecond Number of milliseconds to wait. - - @returns WaitOnConnect returns @true if the connection request completes. + + @return WaitOnConnect returns @true if the connection request completes. This does not necessarily mean that the connection was successfully established; it might also happen that the connection was refused by the peer. Use IsConnected to @@ -301,6 +303,7 @@ public: }; + /** @class wxSockAddress @wxheader{socket.h} @@ -310,8 +313,7 @@ public: @library{wxbase} @category{FIXME} - @seealso - wxSocketBase, wxIPaddress, wxIPV4address + @see wxSocketBase, wxIPaddress, wxIPV4address */ class wxSockAddress : public wxObject { @@ -338,6 +340,7 @@ public: }; + /** @class wxSocketEvent @wxheader{socket.h} @@ -347,8 +350,7 @@ public: @library{wxnet} @category{net} - @seealso - wxSocketBase, wxSocketClient, wxSocketServer + @see wxSocketBase, wxSocketClient, wxSocketServer */ class wxSocketEvent : public wxEvent { @@ -377,6 +379,7 @@ public: }; + /** @class wxSocketBase @wxheader{socket.h} @@ -396,8 +399,7 @@ public: @library{wxnet} @category{net} - @seealso - wxSocketEvent, wxSocketClient, wxSocketServer, @ref overview_samplesockets + @see wxSocketEvent, wxSocketClient, wxSocketServer, @ref overview_samplesockets "Sockets sample" */ class wxSocketBase : public wxObject @@ -420,42 +422,42 @@ public: /** Functions that perform basic IO functionality. Close() - + Discard() - + Peek() - + Read() - + ReadMsg() - + Unread() - + Write() - + WriteMsg() Functions that perform a timed wait on a certain IO condition. InterruptWait() - + Wait() - + WaitForLost() - + WaitForRead() - + WaitForWrite() - + and also: wxSocketServer::WaitForAccept - + wxSocketClient::WaitOnConnect Functions that allow applications to customize socket IO as needed. GetFlags() - + SetFlags() - + SetTimeout() - + SetLocal() */ @@ -472,9 +474,9 @@ public: /** @ref construct() wxSocketBase - + @ref destruct() ~wxSocketBase - + Destroy() */ @@ -487,8 +489,8 @@ public: events have been processed. For the same reason, you should avoid creating socket objects in the stack. Destroy calls Close() automatically. - - @returns Always @true. + + @return Always @true. */ bool Destroy(); @@ -522,8 +524,8 @@ public: This function returns the local address field of the socket. The local address field contains the complete local address of the socket (local address, local port, ...). - - @returns @true if no error happened, @false otherwise. + + @return @true if no error happened, @false otherwise. */ bool GetLocal(wxSockAddress& addr) const; @@ -531,21 +533,21 @@ public: This function returns the peer address field of the socket. The peer address field contains the complete peer host address of the socket (address, port, ...). - - @returns @true if no error happened, @false otherwise. + + @return @true if no error happened, @false otherwise. */ bool GetPeer(wxSockAddress& addr) const; /** Functions that allow applications to receive socket events. Notify() - + SetNotify() - + GetClientData() - + SetClientData() - + SetEventHandler() */ @@ -626,14 +628,14 @@ public: Peeking a buffer doesn't delete it from the socket input queue. Use LastCount() to verify the number of bytes actually peeked. Use Error() to determine if the operation succeeded. - + @param buffer Buffer where to put peeked data. @param nbytes Number of bytes. - - @returns Returns a reference to the current object. - + + @return Returns a reference to the current object. + @see Error(), LastError(), LastCount(), SetFlags() */ @@ -643,14 +645,14 @@ public: This function reads a buffer of @a nbytes bytes from the socket. Use LastCount() to verify the number of bytes actually read. Use Error() to determine if the operation succeeded. - + @param buffer Buffer where to put read data. @param nbytes Number of bytes. - - @returns Returns a reference to the current object. - + + @return Returns a reference to the current object. + @see Error(), LastError(), LastCount(), SetFlags() */ @@ -663,14 +665,14 @@ public: buffer to be entirely filled, unless an error occurs. Use LastCount() to verify the number of bytes actually read. Use Error() to determine if the operation succeeded. - + @param buffer Buffer where to put read data. @param nbytes Size of the buffer. - - @returns Returns a reference to the current object. - + + @return Returns a reference to the current object. + @see Error(), LastError(), LastCount(), SetFlags(), WriteMsg() */ @@ -680,7 +682,7 @@ public: This function restores the previous state of the socket, as saved with SaveState() Calls to SaveState and RestoreState can be nested. - + @see SaveState() */ void RestoreState(); @@ -692,7 +694,7 @@ public: Notify(), user data, as set with SetClientData(). Calls to SaveState and RestoreState can be nested. - + @see RestoreState() */ void SaveState(); @@ -709,12 +711,12 @@ public: handler will be called for those events for which notification is enabled with SetNotify() and Notify(). - + @param handler Specifies the event handler you want to use. @param id The id of socket event. - + @see SetNotify(), Notify(), wxSocketEvent, wxEvtHandler */ void SetEventHandler(wxEvtHandler& handler, int id = -1); @@ -723,36 +725,36 @@ public: Use SetFlags to customize IO operation for this socket. The @a flags parameter may be a combination of flags ORed together. The following flags can be used: - + @b wxSOCKET_NONE - + Normal functionality. - + @b wxSOCKET_NOWAIT - + Read/write as much data as possible and return immediately. - + @b wxSOCKET_WAITALL - + Wait for all required data to be read/written unless an error occurs. - + @b wxSOCKET_BLOCK - + Block the GUI (do not yield) while reading/writing data. - + @b wxSOCKET_REUSEADDR - + Allows the use of an in-use port (wxServerSocket only) - + @b wxSOCKET_BROADCAST - + Switches the socket to broadcast mode - + @b wxSOCKET_NOBIND - + Stops the socket from being bound to a specific adapter (normally used in conjunction with @b wxSOCKET_BROADCAST) - + A brief overview on how to use these flags follows. If no flag is specified (this is the same as @b wxSOCKET_NONE), IO calls will return after some data has been read or written, even @@ -824,25 +826,25 @@ public: SetNotify specifies which socket events are to be sent to the event handler. The @a flags parameter may be combination of flags ORed together. The following flags can be used: - + @b wxSOCKET_INPUT_FLAG - + to receive wxSOCKET_INPUT - + @b wxSOCKET_OUTPUT_FLAG - + to receive wxSOCKET_OUTPUT - + @b wxSOCKET_CONNECTION_FLAG - + to receive wxSOCKET_CONNECTION - + @b wxSOCKET_LOST_FLAG - + to receive wxSOCKET_LOST - + For example: - + In this example, the user will be notified about incoming socket data and whenever the connection is closed. For more information on socket events see @ref overview_wxsocketbase "wxSocket @@ -861,24 +863,24 @@ public: /** Functions to retrieve current state and miscellaneous info. Error() - + GetLocal() - + GetPeer() IsConnected() - + IsData() - + IsDisconnected() - + LastCount() - + LastError() - + IsOk() - + SaveState() - + RestoreState() */ @@ -888,21 +890,21 @@ public: in the incoming queue. This function is not affected by wxSocket flags. If you use LastCount(), it will always return @e nbytes. If you use Error(), it will always return @false. - + @param buffer Buffer to be unread. @param nbytes Number of bytes. - - @returns Returns a reference to the current object. - + + @return Returns a reference to the current object. + @see Error(), LastCount(), LastError() */ wxSocketBase Unread(const void* buffer, wxUint32 nbytes); /** This function waits until any of the following conditions is @true: - + The socket becomes readable. The socket becomes writable. An ongoing connection request has completed (wxSocketClient only) @@ -910,17 +912,17 @@ public: The connection has been closed. Note that it is recommended to use the individual Wait functions to wait for the required condition, instead of this one. - + @param seconds Number of seconds to wait. If -1, it will wait for the default timeout, as set with SetTimeout. @param millisecond Number of milliseconds to wait. - - @returns Returns @true when any of the above conditions is satisfied, + + @return Returns @true when any of the above conditions is satisfied, @false if the timeout was reached. - + @see InterruptWait(), wxSocketServer::WaitForAccept, WaitForLost(), WaitForRead(), WaitForWrite(), wxSocketClient::WaitOnConnect @@ -930,20 +932,20 @@ public: /** This function waits until the connection is lost. This may happen if the peer gracefully closes the connection or if the connection breaks. - + @param seconds Number of seconds to wait. If -1, it will wait for the default timeout, as set with SetTimeout. @param millisecond Number of milliseconds to wait. - - @returns Returns @true if the connection was lost, @false if the timeout + + @return Returns @true if the connection was lost, @false if the timeout was reached. - + @see InterruptWait(), Wait() */ - bool Wait(long seconds = -1, long millisecond = 0); + bool WaitForLost(long seconds = -1, long millisecond = 0); /** This function waits until the socket is readable. This might mean that @@ -951,16 +953,16 @@ public: the connection has been closed, so that a read operation will complete immediately without blocking (unless the @b wxSOCKET_WAITALL flag is set, in which case the operation might still block). - + @param seconds Number of seconds to wait. If -1, it will wait for the default timeout, as set with SetTimeout. @param millisecond Number of milliseconds to wait. - - @returns Returns @true if the socket becomes readable, @false on timeout. - + + @return Returns @true if the socket becomes readable, @false on timeout. + @see InterruptWait(), Wait() */ bool WaitForRead(long seconds = -1, long millisecond = 0); @@ -971,16 +973,16 @@ public: connection has been closed, so that a write operation is guaranteed to complete immediately (unless the @b wxSOCKET_WAITALL flag is set, in which case the operation might still block). - + @param seconds Number of seconds to wait. If -1, it will wait for the default timeout, as set with SetTimeout. @param millisecond Number of milliseconds to wait. - - @returns Returns @true if the socket becomes writable, @false on timeout. - + + @return Returns @true if the socket becomes writable, @false on timeout. + @see InterruptWait(), Wait() */ bool WaitForWrite(long seconds = -1, long millisecond = 0); @@ -989,14 +991,14 @@ public: This function writes a buffer of @a nbytes bytes to the socket. Use LastCount() to verify the number of bytes actually written. Use Error() to determine if the operation succeeded. - + @param buffer Buffer with the data to be sent. @param nbytes Number of bytes. - - @returns Returns a reference to the current object. - + + @return Returns a reference to the current object. + @see Error(), LastError(), LastCount(), SetFlags() */ @@ -1010,18 +1012,19 @@ public: buffer to be sent, unless an error occurs. Use LastCount() to verify the number of bytes actually written. Use Error() to determine if the operation succeeded. - + @param buffer Buffer with the data to be sent. @param nbytes Number of bytes to send. - - @returns Returns a reference to the current object. + + @return Returns a reference to the current object. */ wxSocketBase WriteMsg(const void* buffer, wxUint32 nbytes); }; + /** @class wxDatagramSocket @wxheader{socket.h} @@ -1030,8 +1033,7 @@ public: @library{wxnet} @category{FIXME} - @seealso - wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount, + @see wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount, wxSocketBase::SetFlags, */ class wxDatagramSocket : public wxSocketBase @@ -1039,7 +1041,7 @@ class wxDatagramSocket : public wxSocketBase public: /** Constructor. - + @param flags Socket flags (See wxSocketBase::SetFlags) */ @@ -1054,7 +1056,7 @@ public: This function reads a buffer of @a nbytes bytes from the socket. Use wxSocketBase::LastCount to verify the number of bytes actually read. Use wxSocketBase::Error to determine if the operation succeeded. - + @param address Any address - will be overwritten with the address of the peer that sent that data. @@ -1062,10 +1064,10 @@ public: Buffer where to put read data. @param nbytes Number of bytes. - - @returns Returns a reference to the current object, and the address of + + @return Returns a reference to the current object, and the address of the peer that sent the data on address param. - + @see wxSocketBase::Error, wxSocketBase::LastError, wxSocketBase::LastCount, wxSocketBase::SetFlags, */ @@ -1077,17 +1079,18 @@ public: This function writes a buffer of @a nbytes bytes to the socket. Use wxSocketBase::LastCount to verify the number of bytes actually wrote. Use wxSocketBase::Error to determine if the operation succeeded. - + @param address The address of the destination peer for this data. @param buffer Buffer where read data is. @param nbytes Number of bytes. - - @returns Returns a reference to the current object. + + @return Returns a reference to the current object. */ wxDatagramSocket SendTo(const wxSockAddress& address, const void* buffer, wxUint32 nbytes); }; +