docs/latex/wx/dgramsocket.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        dgramsocket.tex
   3 %% Purpose:     wxSocket docs
   4 %% Author:      Angel Vidal Veiga (kry@amule.org)
   5 %% Modified by:
   6 %% Created:     2006
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) wxWidgets team
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 % ---------------------------------------------------------------------------
  13 % CLASS wxDatagramSocket
  14 % ---------------------------------------------------------------------------
  15
  16 \section{\class{wxDatagramSocket}}\label{wxdatagramsocket}
  17
  18 \wxheading{Derived from}
  19
  20 \helpref{wxSocketBase}{wxsocketbase}
  21
  22 \wxheading{Include files}
  23
  24 <wx/socket.h>
  25
  26 \latexignore{\rtfignore{\wxheading{Members}}}
  27
  28 % ---------------------------------------------------------------------------
  29 % Members
  30 % ---------------------------------------------------------------------------
  31 %
  32 % wxDatagramSocket
  33 %
  34 \membersection{wxDatagramSocket::wxDatagramSocket}\label{wxdatagramsocketctor}
  35
  36 \func{}{wxDatagramSocket}{\param{wxSocketFlags}{ flags = wxSOCKET\_NONE}}
  37
  38 Constructor.
  39
  40 \wxheading{Parameters}
  41
  42 \docparam{flags}{Socket flags (See \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags})}
  43
  44 %
  45 % ~wxDatagramSocket
  46 %
  47 \membersection{wxDatagramSocket::\destruct{wxDatagramSocket}}\label{wxdatagramsocketdtor}
  48
  49 \func{}{\destruct{wxDatagramSocket}}{\void}
  50
  51 Destructor. Please see \helpref{wxSocketBase::Destroy}{wxsocketbasedestroy}.
  52
  53 %
  54 % Connect
  55 %
  56 \membersection{wxDatagramSocket::Connect}\label{wxdatagramsocketconnect}
  57
  58 \func{bool}{Connect}{\param{wxSockAddress\&}{ address}}
  59
  60 Connects to another peer using the specified address.
  61
  62 Connecting in an UDP socket like the one wxDatagramSocket creates is different
  63 from TCP socket's idea of connect. Give then fact that UDP is a connectionless
  64 protocol, the meaning of wxDatagramSocket::Connect is that of the unix connect()
  65 call when used with with UDP sockets. This means the socket send/receive will be bind
  66 to the wxSockAddress specified, and no datagrams will be send or received from other
  67 address.
  68
  69 The Connect() call can be isued several times with no drawbacks, to change the destination
  70 adddress.
  71
  72 {\bf Warning:} When a Connect() has been called on a socket, calling \helpref{ReceiveFrom}{wxdatagramsocketreceivefrom} or \helpref{SendTo}{wxdatagramsocketsendto} with a different wxSockAddress will result in an assertion on debug mode and
  73 no data being sent/received on both debug and release modes. Use
  74 \helpref{Read()}{wxsocketbaseread} and \helpref{Write()}{wxsocketbasewrite}
  75 after calling Connect() to make sure you're reading from/writing to the proper destination.
  76
  77 \wxheading{Parameters}
  78
  79 \docparam{address}{Address of the destination peer.}
  80
  81 \wxheading{Return value}
  82
  83 Returns true if the connect() call is successful and socket is correctly
  84 attached to the destination address.
  85
  86 \wxheading{See also}
  87
  88 \helpref{wxDatagramSocket::Disconnect}{wxdatagramsocketdisconnect},
  89
  90 \newsince{2.7.0} { There was no way to Connect() an wxDatagramSocket before }.
  91
  92 %
  93 % Disconnect
  94 %
  95 \membersection{wxDatagramSocket::Disconnect}\label{wxdatagramsocketdisconnect}
  96
  97 \func{bool}{Disconnect}{}
  98
  99 Removes previously bind to an specific destination address set by a
 100 \helpref{Connect()}{wxdatagramsocketconnect} call.
 101
 102 The Disconnect() call can be isued several times with no drawbacks. No error is set
 103 if the socket was not connected.
 104
 105
 106 \wxheading{Parameters}
 107
 108
 109 \wxheading{Return value}
 110
 111 Returns true if the socket was sucessfully deatached from the destination address.
 112
 113 \wxheading{See also}
 114
 115 \helpref{wxDatagramSocket::Connect}{wxdatagramsocketconnect},
 116
 117 \newsince{2.7.0} { There was no way to Connect() an wxDatagramSocket before. }
 118
 119 %
 120 % ReceiveFrom
 121 %
 122 \membersection{wxDatagramSocket::ReceiveFrom}\label{wxdatagramsocketreceivefrom}
 123
 124 \func{wxDatagramSocket\&}{ReceiveFrom}{\param{wxSockAddress\&}{ address}, \param{void *}{ buffer}, \param{wxUint32}{ nbytes}}
 125
 126 This function reads a buffer of {\it nbytes} bytes from the socket.
 127
 128 Use \helpref{LastCount}{wxsocketbaselastcount} to verify the number of bytes actually read.
 129
 130 Use \helpref{Error}{wxsocketbaseerror} to determine if the operation succeeded.
 131
 132 \wxheading{Parameters}
 133
 134 \docparam{address}{Any address - will be overwritten with the address of the peer that sent that data.}
 135
 136 \docparam{buffer}{Buffer where to put read data.}
 137
 138 \docparam{nbytes}{Number of bytes.}
 139
 140 \wxheading{Return value}
 141
 142 Returns a reference to the current object, and the address of the peer that sent the data on address param.
 143
 144 \wxheading{Remark/Warning}
 145
 146 If a \helpref{Connect()}{wxdatagramsocketconnect} call is issued before ReceiveFrom is called,
 147 the address sent on this call MUST match the one ussed on the Connect() call, or this call will assert. It's usually a good idea to use \helpref{wxSocketBase::Read}{wxsocketbaseread} in this case.
 148
 149 \wxheading{See also}
 150
 151 \helpref{wxSocketBase::Error}{wxsocketbaseerror},
 152 \helpref{wxSocketBase::LastError}{wxsocketbaselasterror},
 153 \helpref{wxSocketBase::LastCount}{wxsocketbaselastcount},
 154 \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags},
 155 \helpref{Connect()}{wxdatagramsocketconnect}
 156
 157 %
 158 % SendTo
 159 %
 160 \membersection{wxDatagramSocket::SendTo}\label{wxdatagramsocketsendto}
 161
 162 \func{wxDatagramSocket\&}{SendTo}{\param{const wxSockAddress\&}{ address}, \param{const void *}{ buffer}, \param{wxUint32}{ nbytes}}
 163
 164 This function writes a buffer of {\it nbytes} bytes to the socket.
 165
 166 Use \helpref{LastCount}{wxsocketbaselastcount} to verify the number of bytes actually wrote.
 167
 168 Use \helpref{Error}{wxsocketbaseerror} to determine if the operation succeeded.
 169
 170 \wxheading{Parameters}
 171
 172 \docparam{address}{The address of the destination peer for this data.}
 173
 174 \docparam{buffer}{Buffer where read data is.}
 175
 176 \docparam{nbytes}{Number of bytes.}
 177
 178 \wxheading{Return value}
 179
 180 Returns a reference to the current object.
 181
 182 \wxheading{Remark/Warning}
 183
 184 If a \helpref{Connect()}{wxdatagramsocketconnect} call is issued before SendTo is called,
 185 the address sent on this call MUST match the one ussed on the Connect() call, or this call will assert. It's usually a good idea to use \helpref{wxSocketBase::Write}{wxsocketbasewrite} in this case.
 186
 187 \wxheading{See also}
 188
 189 \helpref{wxSocketBase::Error}{wxsocketbaseerror},
 190 \helpref{wxSocketBase::LastError}{wxsocketbaselasterror},
 191 \helpref{wxSocketBase::LastCount}{wxsocketbaselastcount},
 192 \helpref{wxSocketBase::SetFlags}{wxsocketbasesetflags}
 193 \helpref{Connect()}{wxdatagramsocketconnect}