station_8h-source.html

用来介绍ZIG Library游戏网络引擎的文档

00141         <span class="keywordtype">bool</span> ack_expected;              <span class="comment">//is the ack of this message being expected?</span>
00142         <span class="keywordtype">bool</span> critical; <span class="comment">//critical message?</span>
00143         std::vector&lt;NLushort&gt; sends; <span class="comment">//id of every packet that sent this message until now</span>
00144         <a class="code" href="classbuffer__c.html">buffer_c</a> body; <span class="comment">//the message body</span>
00145 };
00146 
00147 <span class="comment">//enum of policies for outgoing reliable messages</span>
00148 <span class="comment">// FIXME : implement the lower priorities</span>
00149 <span class="comment">// v1.3.0: enum moved to zig.h</span>
00150         <span class="comment">//RSP_HIGH,                                                             //non-delayable, minimum interval=1 between sends</span>
00151         <span class="comment">//RSP_MEDIUM,                                                   //delayable if packet is big, minimum interval=1 between sends</span>
00152         <span class="comment">//RSP_LOW,                                                              //delayable if packet is big, minimum interval=2 between sends</span>
00153         <span class="comment">//RSP_LOWEST,                                                   //will only send when packet is small, minimum interval between sends=3</span>
00154 
00155 
00156 <span class="comment">//reliable UDP socket+brains</span>
00157 <span class="keyword">class </span>station_c {
00158 <span class="keyword">public</span>:
00159 
00160         <span class="comment">//ctor</span>
00161         station_c();
00162 
00163         <span class="comment">//dtor calls close() and then destroys mutexes etc.</span>
00164         <span class="keyword">virtual</span> ~station_c();
00165 
00166         <span class="comment">//set debug string</span>
00167         <span class="keywordtype">void</span> set_debug(<span class="keywordtype">char</span> *debugstr) { <span class="keywordflow">if</span> (strlen(debugstr) &lt; 64) strcpy(dstr, debugstr); }
00168 
00169         <span class="comment">//set console</span>
00170         <span class="keywordtype">void</span> set_console(<a class="code" href="classconsole__c.html">console_c</a> *conio);
00171 
00172         <span class="comment">// configure usage of packet compression. to turn on the sending of compressed packets at any time, </span>
00173         <span class="comment">// pass a value &gt;=0 as argument, which specifies the minimum size that the packet must have, in bytes, </span>
00174         <span class="comment">// to be compressed (pass 0 to compress all outgoing packets). to turn off the sending of compressed </span>
00175         <span class="comment">// packets at any time, call this method with no parameters (or a negative value as parameter). </span>
00176         <span class="comment">// NOTE: this call resets the compression stats.</span>
00177         <span class="keywordtype">void</span> set_compression(<span class="keywordtype">int</span> minimum_packet_size = -1) { compression_config = minimum_packet_size; }
00178 
00179         <span class="comment">// open/reopen local socket. returns 0 on failure, returns local port number on success. resets state.</span>
00180         <span class="comment">// tcp_master: if true, this station can request "channel open" to the station in the other side.</span>
00181         <span class="comment">// tcp_listen_port: the port where TCP connections are expected (0 if none)</span>
00182         <span class="keywordtype">int</span> open(<span class="keywordtype">int</span> udp_port, <span class="keywordtype">bool</span> tcp_master, <span class="keywordtype">int</span> tcp_listen_port);
00183 
00184         <span class="comment">// close local socket. resets state.</span>
00185         <span class="keywordtype">int</span> close();
00186 
00187         <span class="comment">// set/change the remote address. returns 0 on failure, 1 on success. notation is "bla.bla.bla.bla:portnum". resets state.</span>
00188         <span class="keywordtype">int</span> set_remote_address(<span class="keywordtype">char</span>* address);
00189 
00190         <span class="comment">// set/change the remote address. returns 0 on failure, 1 on success. NL address struct. resets state.</span>
00191         <span class="keywordtype">int</span> set_remote_address(NLaddress some_addr);
00192 
00193         <span class="comment">//change the port of the remote address. resets state.</span>
00194         <span class="keywordtype">int</span> set_remote_port(NLushort port);
00195 
00196         <span class="comment">// set remote listening TCP port. defaults to 0 (none)</span>
00197         <span class="keywordtype">void</span> set_remote_tcp_listen_port(<span class="keywordtype">int</span> port) { tcp_remote_listen_port = port; }
00198 
00199         <span class="comment">//get the port of the remote address</span>
00200         NLushort get_remote_port();
00201 
00202         <span class="comment">//get the port of the local address</span>
00203         NLushort get_local_port();
00204         
00205         <span class="comment">// unblock when blocked on receive_packet()</span>
00206         <span class="keywordtype">bool</span> unblock_receive();
00207 
00208         <span class="comment">// get the address of the last receive_packet() call (nlRead()...)</span>
00209         NLaddress &amp;get_received_address();
00210 
00211         <span class="comment">// NEW: polling multiple stations support: </span>
00212         <span class="comment">// get this station's internal socket object. currently you will need it you want to poll several </span>
00213         <span class="comment">// stations for read/write status. </span>
00214         NLsocket get_socket();
00215 
00216         <span class="comment">// NEW: polling multiple stations support: </span>
00217         <span class="comment">// do a NON-BLOCKING read from the socket. returns READ_PACKET_INTERNAL if the data was consumed internally by the </span>
00218         <span class="comment">// station protocol, else returns the data read in buf (if any) and the return value of nlRead().</span>
00219   <span class="keywordtype">int</span> read_packet(<a class="code" href="classbuffer__c.html">buffer_c</a> &amp;buf);
00220 
00221         <span class="comment">// BLOCKING call: attempt to read data from the socket. buf: pre-created buffer given to the routine. </span>
00222         <span class="comment">// int return: value of nlRead()... :-).</span>
00223         <span class="keywordtype">int</span> receive_packet(<a class="code" href="classbuffer__c.html">buffer_c</a> &amp;buf);
00224 
00225         <span class="comment">// BLOCKING call: attempt to read data from the socket. pass 0(NULL) if not interested.</span>
00226         <span class="comment">// buffer_c return: a buffer object containing the data and ".code" of nlRead.</span>
00227         <a class="code" href="classbuffer__c.html">buffer_c</a> receive_packet();
00228 
00229         <span class="comment">// process incoming packet. returns unreliable data portion of packet. also returns in the ".code"</span>
00230         <span class="comment">// field of the buffer_c returned, the type of packet that arrived. possible types:</span>
00231         <span class="comment">// STATION_INCOMING_PACKET_NORMAL: a regular game packet</span>
00232         <span class="comment">// STATION_INCOMING_PACKET_SPECIAL: a special packet (sent with send_raw_packet())</span>
00233         <span class="comment">// STATION_INCOMING_PACKET_REQUEST: a request packet generated by a make_request() call. you must call</span>
00234         <span class="comment">//   answer_request() to answer this request. the ".id" field of the buffer_c returned contains the</span>
00235         <span class="comment">//   id of this request that you must pass into the answer_request() call.</span>
00236         <span class="comment">// "packet_id_ptr" is an optional pointer to an int which will receive the id of the incoming packet.</span>
00237         <a class="code" href="classbuffer__c.html">buffer_c</a> process_incoming_packet(<a class="code" href="classbuffer__c.html">buffer_c</a> &amp;packet, <span class="keywordtype">int</span> *packet_id_ptr = 0);
00238 
00239         <span class="comment">// reads next reliable message in the arrival queue into the supplied buffer. </span>
00240         <span class="comment">// returns 0 if no more messages to read, 1 if success.</span>
00241         <span class="keywordtype">int</span> read_reliable(<a class="code" href="classbuffer__c.html">buffer_c</a> &amp;msg);
00242 
00243         <span class="comment">// reads next reliable message in the arrival queue. </span>
00244         <span class="comment">// returns buffer_c with the message and ".code" = 0 if no more messages to read, 1 if success.</span>
00245         <a class="code" href="classbuffer__c.html">buffer_c</a> read_reliable();
00246 
00247         <span class="comment">// appends reliable message to the queue. this will be sent as many times as needed until</span>
00248         <span class="comment">// it's acknowledged by the other side.</span>
00249         <span class="comment">// policy: the priority, or ID of the algorythm used for testing when the message is (re-)transmitted</span>
00250         <span class="comment">// msg_id: if you want to be notified when this message is ACK'ed by the receiver, pass a valid int</span>
00251         <span class="comment">//   pointer via msg_id. the pointer will be filled with the ID of the outgoing message, that can be</span>
00252         <span class="comment">//   used to identify the ack when it comes through read_ack()</span>
00253         <span class="keywordtype">int</span> write_reliable(<a class="code" href="classbuffer__c.html">buffer_c</a> &amp;msg, <span class="keywordtype">int</span> *msg_id = 0, <span class="keywordtype">int</span> policy = RSP_USE_DEFAULT);
00254 
00255         <span class="comment">// read a pending reliable message ack. does not block. returns -1 if no acks to be read,</span>
00256         <span class="comment">// else returns the id of the message that was acked (same "msg_id" of write_reliable())</span>
00257         <span class="comment">// call this after a packet arrives (that's the only time the acks are updated)</span>
00258         <span class="keywordtype">int</span> read_ack();
00259 
00260         <span class="comment">// appends unreliable data to the packet buffer. all these calls are collapsed and the</span>
00261         <span class="comment">// unreliable data is sent as a big chunk when send_packet() is called (see below).</span>
00262         <span class="keywordtype">int</span> write(<a class="code" href="classbuffer__c.html">buffer_c</a> &amp;data);
00263 
00264         <span class="comment">// flush the packet buffers as an UDP packet to the remote address, returns "id"</span>
00265         <span class="comment">// for the assigned packet id. this call resets the unreliable data buffer (see write() above).</span>
00266         <span class="comment">// optional parameter: rskip: if TRUE, sends none of the reliable messages pending</span>
00267         <span class="comment">// POSSIBLE RETURN CODES: </span>
00268         <span class="comment">//   SENDPACKET_OK                     0    // no error</span>
00269   <span class="comment">//   SENDPACKET_SOCKET_ERROR          -1    // when nlWrite() returns NL_INVALID</span>
00270         <span class="comment">//   SENDPACKET_CRITICAL_OVERFLOW     -2    // protocol limitation: excess of pending outbound critical messages</span>
00271         <span class="comment">//   SENDPACKET_ACKDELTA_OVERFLOW     -3    // protocol limitation: "jump" between two outbound ack IDs encoded is greater than -128/+127</span>
00272         <span class="comment">//   SENDPACKET_RELDELTA_OVERFLOW     -4    // protocol limitation: "jump" between two outbound reliable message IDs encoded is greater than -128/+127</span>
00273         <span class="keywordtype">int</span> send_packet(<span class="keywordtype">int</span> *id, <span class="keywordtype">bool</span> rskip = <span class="keyword">false</span>);
00274 
00275         <span class="comment">// send a raw UDP packet to the destination. use when you want to send a message to the other</span>
00276         <span class="comment">// side without the "RUDP protocol" overhead. UDP packets with the first short == 0 are "special"</span>
00277         <span class="comment">// and not treated as rudp packets (see process_incoming_packet()). returns result of nlWrite()</span>
00278         <span class="keywordtype">int</span> send_raw_packet(<a class="code" href="classbuffer__c.html">buffer_c</a> &amp;udp);
00279 
00280         <span class="comment">// reliably sends a "request" to the other side using UDP, and returns the "response". this</span>
00281         <span class="comment">// call blocks until the response is read, or the request times out.</span>
00282         <span class="comment">// arguments: timeout in ms, interval (in ms) between each packet send, and time for sending</span>
00283         <span class="comment">//   packets (less than or equal to timeout_ms),</span>
00284         <span class="comment">// default value for send_ms is 3/4 of the value of timeout_ms (signaled by the -1 default value)</span>
00285         <span class="comment">// returns the response. if response's .code == 1, then the request timed out.</span>