X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/08f1d4387331d652b8297e6a4aef782b921bad5e..c266eff98c5e44012647f54f38a1e29ecabd8759:/docs/latex/wx/socket.tex diff --git a/docs/latex/wx/socket.tex b/docs/latex/wx/socket.tex index 096c6a9f18..52685b58cf 100644 --- a/docs/latex/wx/socket.tex +++ b/docs/latex/wx/socket.tex @@ -6,7 +6,7 @@ %% Created: 1999 %% RCS-ID: $Id$ %% Copyright: (c) wxWidgets team -%% License: wxWidgets license +%% License: wxWindows license %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{\class{wxSocketBase}}\label{wxsocketbase} @@ -29,6 +29,10 @@ http://www.litwindow.com/knowhow/knowhow.html for more details. +\wxheading{Library} + +\helpref{wxNet}{librarieslist} + \wxheading{wxSocket errors} \twocolwidtha{7cm} @@ -127,7 +131,7 @@ Functions to retrieve current state and miscellaneous info. \helpref{IsDisconnected}{wxsocketbaseisdisconnected}\\ \helpref{LastCount}{wxsocketbaselastcount}\\ \helpref{LastError}{wxsocketbaselasterror}\\ -\helpref{Ok}{wxsocketbaseok}\\ +\helpref{IsOk}{wxsocketbaseisok}\\ \helpref{SaveState}{wxsocketbasesavestate}\\ \helpref{RestoreState}{wxsocketbaserestorestate} @@ -161,7 +165,8 @@ Functions that allow applications to customize socket IO as needed. \helpref{GetFlags}{wxsocketbasegetflags}\\ \helpref{SetFlags}{wxsocketbasesetflags}\\ -\helpref{SetTimeout}{wxsocketbasesettimeout} +\helpref{SetTimeout}{wxsocketbasesettimeout}\\ +\helpref{SetLocal}{wxsocketbasesetlocal}\\ \membersection{Handling socket events}\label{socketevents} @@ -173,14 +178,6 @@ Functions that allow applications to receive socket events. \helpref{SetClientData}{wxsocketbasesetclientdata}\\ \helpref{SetEventHandler}{wxsocketbaseseteventhandler} -Callback functions are also available, but they are provided for backwards -compatibility only. Their use is strongly discouraged in favour of events, -and should be considered deprecated. Callbacks may be unsupported in future -releases of wxWidgets. - -\helpref{Callback}{wxsocketbasecallback}\\ -\helpref{CallbackData}{wxsocketbasecallbackdata} - % --------------------------------------------------------------------------- % Members here @@ -208,67 +205,6 @@ Destructor. Do not destroy a socket using the delete operator directly; use \helpref{Destroy}{wxsocketbasedestroy} instead. Also, do not create socket objects in the stack. -% -% Callback -% -\membersection{wxSocketBase::Callback}\label{wxsocketbasecallback} - -\func{wxSocketBase::wxSockCbk}{Callback}{\param{wxSocketBase::wxSockCbk}{ callback}} - -You can setup a callback function to be called when an event occurs. -The function will be called only for those events for which notification -has been enabled with \helpref{Notify}{wxsocketbasenotify} and -\helpref{SetNotify}{wxsocketbasesetnotify}. The prototype of the -callback must be as follows: - -\begin{verbatim} -void SocketCallback(wxSocketBase& sock, wxSocketNotify evt, char *cdata); -\end{verbatim} - -The first parameter is a reference to the socket object in which the -event occurred. The second parameter tells you which event occurred. -(See \helpref{wxSocket events}{wxsocketbase}). The third parameter -is the user data you specified using \helpref{CallbackData}{wxsocketbasecallbackdata}. - -\wxheading{Return value} - -A pointer to the previous callback. - -\wxheading{Remark/Warning} - -Note that callbacks are now deprecated and unsupported, and they remain -for backwards compatibility only. Use events instead. - -\wxheading{See also} - -\helpref{wxSocketBase::CallbackData}{wxsocketbasecallbackdata}, -\helpref{wxSocketBase::SetNotify}{wxsocketbasesetnotify}, -\helpref{wxSocketBase::Notify}{wxsocketbasenotify} - -% -% CallbackData -% -\membersection{wxSocketBase::CallbackData}\label{wxsocketbasecallbackdata} - -\func{char *}{CallbackData}{\param{char *}{cdata}} - -This function sets the the user data which will be passed to a -callback function set via \helpref{Callback}{wxsocketbasecallback}. - -\wxheading{Return value} - -A pointer to the previous user data. - -\wxheading{Remark/Warning} - -Note that callbacks are now deprecated and unsupported, and they remain -for backwards compatibility only. Use events instead. - -\wxheading{See also} - -\helpref{wxSocketBase::Callback}{wxsocketbasecallback}, -\helpref{wxSocketBase::SetNotify}{wxsocketbasesetnotify}, -\helpref{wxSocketBase::Notify}{wxsocketbasenotify} % % Close @@ -482,11 +418,11 @@ be sent to the application. If {\it notify} is false; no events will be sent. % -% Ok +% IsOk % -\membersection{wxSocketBase::Ok}\label{wxsocketbaseok} +\membersection{wxSocketBase::IsOk}\label{wxsocketbaseisok} -\constfunc{bool}{Ok}{\void} +\constfunc{bool}{IsOk}{\void} Returns true if the socket is initialized and ready and false in other cases. @@ -530,9 +466,7 @@ This function saves the current state of the socket in a stack. Socket state includes flags, as set with \helpref{SetFlags}{wxsocketbasesetflags}, event mask, as set with \helpref{SetNotify}{wxsocketbasesetnotify} and \helpref{Notify}{wxsocketbasenotify}, user data, as set with -\helpref{SetClientData}{wxsocketbasesetclientdata}, and asynchronous -callback settings, as set with \helpref{Callback}{wxsocketbasecallback} -and \helpref{CallbackData}{wxsocketbasecallbackdata}. +\helpref{SetClientData}{wxsocketbasesetclientdata}. Calls to SaveState and RestoreState can be nested. @@ -594,6 +528,8 @@ The following flags can be used: \twocolitem{{\bf wxSOCKET\_WAITALL}}{Wait for all required data to be read/written unless an error occurs.} \twocolitem{{\bf wxSOCKET\_BLOCK}}{Block the GUI (do not yield) while reading/writing data.} \twocolitem{{\bf wxSOCKET\_REUSEADDR}}{Allows the use of an in-use port (wxServerSocket only)} +\twocolitem{{\bf wxSOCKET\_BROADCAST}}{Switches the socket to broadcast mode} +\twocolitem{{\bf wxSOCKET\_NOBIND}}{Stops the socket from being bound to a specific adapter (normally used in conjunction with {\bf wxSOCKET\_BROADCAST})} \end{twocollist} A brief overview on how to use these flags follows. @@ -631,8 +567,16 @@ The {\bf wxSOCKET\_REUSEADDR} flag controls the use of the SO\_REUSEADDR standar setsockopt() flag. This flag allows the socket to bind to a port that is already in use. This is mostly used on UNIX-based systems to allow rapid starting and stopping of a server - otherwise you may have to wait several minutes for the port to become available. -This option can have suprising platform dependent behavior, check the documentation for -your platforms implementation of setsockopt(). +wxSOCKET\_REUSEADDR can also be used with socket clients to (re)bind to a particular local port +for an outgoing connection. +This option can have surprising platform dependent behavior, so check the documentation for +your platform's implementation of setsockopt(). Note that on BSD-based systems (e.g. Mac OS X), +use of wxSOCKET\_REUSEADDR implies SO\_REUSEPORT in addition to SO\_REUSEADDR to be consistent +with Windows. + +The {\bf wxSOCKET\_BROADCAST} flag controls the use of the SO\_BROADCAST standard +setsockopt() flag. This flag allows the socket to use the broadcast address, and is generally +used in conjunction with {\bf wxSOCKET\_NOBIND} and \helpref{wxIPaddress::BroadcastAddress}{wxipaddressbroadcastaddress}. So: @@ -647,7 +591,20 @@ the data. {\bf wxSOCKET\_BLOCK} has nothing to do with the previous flags and it controls whether the GUI blocks. -{\bf wxSOCKET\_REUSEADDR} controls special platform-specific behavior for wxServerSocket. +{\bf wxSOCKET\_REUSEADDR} controls special platform-specific behavior for +reusing local addresses/ports. + +% +% SetLocal +% +\membersection{wxSocketBase::SetLocal}\label{wxsocketbasesetlocal} + +\func{bool}{SetLocal}{\param{wxIPV4address\&}{ local}} + +This function allows you to set the local address and port, +useful when an application needs to reuse a particular port. When +a local port is set for a \helpref{wxSocketClient}{wxsocketclient}, +{\bf bind} will be called before {\bf connect}. % % SetNotify @@ -1049,12 +1006,17 @@ For a detailed explanation, see \helpref{wxSocketBase::SetFlags}{wxsocketbaseset \wxheading{Derived from} -\helpref{wxSocketBase}{wxsocketbase} +\helpref{wxSocketBase}{wxsocketbase}\\ +\helpref{wxObject}{wxobject} \wxheading{Include files} +\wxheading{Library} + +\helpref{wxNet}{librarieslist} + \latexignore{\rtfignore{\wxheading{Members}}} % --------------------------------------------------------------------------- @@ -1089,6 +1051,9 @@ Destructor. Please see \helpref{wxSocketBase::Destroy}{wxsocketbasedestroy}. \func{bool}{Connect}{\param{wxSockAddress\&}{ address}, \param{bool}{ wait = true}} +\func{bool}{Connect}{\param{wxSockAddress\&}{ address}, \param{wxSockAddress\&}{ local}, +\param{bool}{ wait = true}} + Connects to a server using the specified address. If {\it wait} is true, Connect will wait until the connection @@ -1105,6 +1070,10 @@ and {\bf wxSOCKET\_LOST} events (for connection failure). \docparam{address}{Address of the server.} +\docparam{local}{Bind to the specified local address and port before connecting. +The local address and port can also be set using \helpref{SetLocal}{wxsocketbasesetlocal}, +and then using the 2-parameter Connect method.} + \docparam{wait}{If true, waits for the connection to complete.} \wxheading{Return value} @@ -1185,12 +1154,17 @@ This event class contains information about socket events. \wxheading{Derived from} -\helpref{wxEvent}{wxevent} +\helpref{wxEvent}{wxevent}\\ +\helpref{wxObject}{wxobject} \wxheading{Include files} +\wxheading{Library} + +\helpref{wxNet}{librarieslist} + \wxheading{Event table macros} To process a socket event, use these event handler macros to direct input