client_8h-source.html

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

00121 
00122         <span class="comment">// configure the amount of time, in seconds, that the client will keep trying to</span>
00123         <span class="comment">// connect to the server, before giving up. the default parameter is the default </span>
00124         <span class="comment">// timeout value.</span>
00125         <span class="keywordtype">void</span> set_connect_timeout(<span class="keywordtype">int</span> timeout = 4) { connect_to_server_timeout = timeout; }
00126 
00127         <span class="comment">// when socket polling mode is enabled, must call this periodically to make ZIG read the client </span>
00128         <span class="comment">// socket and call the data callbacks (leet_incoming_data(), ...). this method does nothing if </span>
00129         <span class="comment">// the client is not connected. </span>
00130         <span class="comment">// RETURN VALUE: -1 if error, 0 if no packet was read/processed, or the number of packets that were </span>
00131         <span class="comment">// read/processed in this call</span>
00132         <span class="keywordtype">int</span> poll_socket();
00133 
00137         <span class="keywordtype">void</span> set_default_send_message_policy(<span class="keywordtype">int</span> send_policy) { default_send_message_policy = send_policy; }
00138 
00139         <span class="comment">//set minimum send reliables interval. set this to the server's net tick time, or</span>
00140         <span class="comment">// some other value, or just leave on default (0.0)</span>
00141         <span class="keywordtype">void</span> set_min_send_reliables_interval(<span class="keywordtype">double</span> interval = 0.0) { min_send_reliables_interval = interval; }
00142 
00143         <span class="comment">// configure usage of packet compression. to turn on the sending of compressed packets at any time, </span>
00144         <span class="comment">// pass a value &gt;=0 as argument, which specifies the minimum size that the packet must have, in bytes, </span>
00145         <span class="comment">// to be compressed (pass 0 to compress all outgoing packets). to turn off the sending of compressed </span>
00146         <span class="comment">// packets at any time, call this method with no parameters (or a negative value as parameter). </span>
00147         <span class="comment">// NOTE: this call resets the compression stats.</span>
00148         <span class="keywordtype">void</span> set_compression(<span class="keywordtype">int</span> minimum_packet_size = -1) { station.set_compression(minimum_packet_size); }
00149 
00150         <span class="comment">//reset object state -- make it ready to connect again</span>
00151         <span class="keywordtype">void</span> reset_state();
00152 
00153         <span class="comment">//if channel_port_num != LEET_CHANNEL_PORT_PUSH, opens a TCP listen socket at given port to listen for</span>
00154         <span class="comment">//"channel" connects from server. doesn't need to be called: if not called, then this client does not</span>
00155         <span class="comment">//support incoming connections from the server.</span>
00156         <span class="keywordtype">void</span> set_channel_listen_port(<span class="keywordtype">int</span> channel_port_num);
00157         
00158         <span class="comment">//set the server's address. call before connect() - address must be a RESOLVED IP!</span>
00159         <span class="comment">//returns true of ok, false if there is already a connection.</span>
00160         <span class="keywordtype">bool</span> set_server_address(<span class="keywordtype">char</span> *address);
00161 
00162         <span class="comment">//set the custom data sent with every connection packet</span>
00163         <span class="keywordtype">void</span> set_connect_data(<a class="code" href="classbuffer__c.html">buffer_c</a> &amp;data);
00164 
00165         <span class="comment">//get information from a server. result comes in the leet_incoming_server_info callback.</span>
00166         <span class="comment">//"custom": optional data to be passed to your game server with the request.</span>
00167         <span class="keywordtype">void</span> get_server_info(<a class="code" href="classaddress__c.html">address_c</a> &amp;addr, <a class="code" href="classbuffer__c.html">buffer_c</a> &amp;custom);
00168 
00169         <span class="comment">//set connection status. if set to TRUE, engine will try to estabilish connection</span>
00170         <span class="comment">//with the server. if set to FALSE, will stop trying to connect or will disconnect</span>
00171         <span class="comment">//results are returned in the client_behavior_i respective callbacks.</span>
00172         <span class="comment">//code reason is just an optional int to be passed to the leet_disconnected() callback</span>
00173         <span class="comment">//when connect(false) is called.</span>
00174         <span class="comment">//returns false if there was some internal error and the request couldn't be</span>
00175         <span class="comment">//  completed (this is a BAD error).</span>
00176         <span class="keywordtype">bool</span> connect(<span class="keywordtype">bool</span> yes, <span class="keywordtype">int</span> code_reason = 0);
00177 
00178         <span class="comment">//is connected?</span>
00179         <span class="keywordtype">bool</span> is_connected() { <span class="keywordflow">return</span> (connect_state.get() == CCS_CONNECTED); }
00180 
00181         <span class="comment">//is not disconnected?</span>
00182         <span class="keywordtype">bool</span> is_not_disconnected() { <span class="keywordflow">return</span> (connect_state.get() != CCS_NOT_CONNECTED); }
00183 
00184         <span class="comment">//send reliable message to server</span>
00185         <span class="comment">//returns 0 on failure, 1 on success</span>
00186         <span class="keywordtype">int</span> send_message(<a class="code" href="classbuffer__c.html">buffer_c</a> &amp;message, <span class="keywordtype">int</span> policy = RSP_USE_DEFAULT);
00187 
00188         <span class="comment">//dispatches the packet with the given unreliable data block and all the</span>
00189         <span class="comment">//protocol overload (reliable messages, acks...)</span>
00190         <span class="comment">//returns 0 on failure, 1 on success</span>
00191         <span class="comment">//returns the allocated packet id in the optional packet_id pointer</span>
00192         <span class="keywordtype">int</span> send_frame(<a class="code" href="classbuffer__c.html">buffer_c</a> &amp;udata, <span class="keywordtype">int</span> *packet_id = 0);
00193 
00194         <span class="comment">//gets the next reliable message avaliable from the server.</span>
00195         <span class="comment">//should be called by the "client behaviour" class inside it's incoming_data(..) method.</span>
00196         <span class="comment">//returns in buffer_c.code: 0 if no more messages, 1 if message valid, -1 if error</span>
00197         <a class="code" href="classbuffer__c.html">buffer_c</a> receive_message();
00198 
00199         <span class="comment">//gets the next reliable message avaliable from the server, puts into the buffer parameter.</span>
00200         <span class="comment">//should be called by the "client behaviour" class inside it's incoming_data(..) method.</span>
00201         <span class="comment">//returns: 0 if no more messages, 1 if message valid, -1 if error</span>
00202         <span class="keywordtype">int</span> receive_message(<a class="code" href="classbuffer__c.html">buffer_c</a> &amp;msgbuf);
00203 
00204         <span class="comment">//---- UDP REQUEST API -----------------------------------------------</span>
00205 
00206         <span class="comment">//answer an incoming request from server_c. see answer_request() in station.h.</span>
00207         <span class="keywordtype">int</span> answer_request(<span class="keywordtype">int</span> request_id, <a class="code" href="classbuffer__c.html">buffer_c</a> &amp;response) { <span class="keywordflow">if</span> (is_connected()) <span class="keywordflow">return</span> station.answer_request(request_id, response); <span class="keywordflow">return</span> NL_INVALID; }
00208 
00209         <span class="comment">//---- CHANNEL WRITE API ---------------------------------------------</span>
00210 
00211         <span class="comment">// channel write. returns result of nlWrite.</span>
00212         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, <a class="code" href="classbuffer__c.html">buffer_c</a> &amp;out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0) { <span class="keywordflow">return</span> station.chan_write(channel_id, out, timeout_is_failure, timeout); }
00213         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, NLubyte out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0) { <span class="keywordflow">return</span> station.chan_write(channel_id, out, timeout_is_failure, timeout); }
00214         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, NLbyte out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0) { <span class="keywordflow">return</span> station.chan_write(channel_id, out, timeout_is_failure, timeout); }
00215         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, NLushort out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0) { <span class="keywordflow">return</span> station.chan_write(channel_id, out, timeout_is_failure, timeout); }
00216         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, NLshort out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0) { <span class="keywordflow">return</span> station.chan_write(channel_id, out, timeout_is_failure, timeout); }
00217         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, NLulong out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0) { <span class="keywordflow">return</span> station.chan_write(channel_id, out, timeout_is_failure, timeout); }
00218         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, NLlong out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0) { <span class="keywordflow">return</span> station.chan_write(channel_id, out, timeout_is_failure, timeout); }
00219         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, NLfloat out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0) { <span class="keywordflow">return</span> station.chan_write(channel_id, out, timeout_is_failure, timeout); }
00220         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, NLdouble out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0) { <span class="keywordflow">return</span> station.chan_write(channel_id, out, timeout_is_failure, timeout); }
00221         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, std::string out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0) { <span class="keywordflow">return</span> station.chan_write(channel_id, out, timeout_is_failure, timeout); }
00222         
00223         <span class="comment">//---- TCP CHANNELS CALLBACKS ----------------------------------------</span>
00224         
00225         <span class="comment">//listen socket is telling the leet client/server of new connection.</span>
00226         <span class="keyword">virtual</span> <span class="keywordtype">void</span> listen_socket_incoming_connection(listen_socket_c *ls, NLsocket sock);
00227 
00228         <span class="comment">//station channel callback: channel opened ok</span>
00229         <span class="keyword">virtual</span> <span class="keywordtype">void</span> station_channel_opened(<span class="keywordtype">int</span> channel_id, <a class="code" href="classchannel__c.html">channel_c</a> *ch, <span class="keywordtype">int</span> tag);
00230 
00231         <span class="comment">//station channel callback: channel open failed</span>
00232         <span class="keyword">virtual</span> <span class="keywordtype">void</span> station_channel_failed(<span class="keywordtype">int</span> channel_id, <span class="keywordtype">int</span> code_reason, <span class="keywordtype">int</span> tag);
00233 
00234 <span class="keyword">protected</span>:
00235 
00236         <span class="comment">//thread run - incoming data from server reader thread function</span>
00237         <span class="keywordtype">void</span> *reader_thread_run(<span class="keywordtype">void</span> *);
00238 
00239         <span class="comment">//shared code between reader_thread_run() and poll_socket()</span>
00240         <span class="keywordtype">void</span> process_packet_read(<span class="keywordtype">int</span> amount, <a class="code" href="classbuffer__c.html">buffer_c</a> pkt);
00241 
00242         <span class="comment">//thread run - connector thread run function</span>
00243         <span class="keywordtype">void</span> *connector_thread_run(<span class="keywordtype">void</span> *);
00244 
00245         <span class="comment">//thread run - get server info thread run</span>
00246         <span class="keywordtype">void</span> *getserverinfo_thread_run(<span class="keywordtype">void</span> *p_addr, <span class="keywordtype">void</span> *p_custom);
00247 
00248         <span class="comment">//important - gets rid of the connector thread if any;</span>
00249         <span class="keywordtype">void</span> join_connector_thread();
00250 
00251         <span class="comment">//important - gets rid of the reader thread if any;</span>