📄 libnet.html
字号:
<html lang="en"><head><title>Libnet Documentation</title><meta http-equiv="Content-Type" content="text/html"><meta name=description content="Libnet Documentation"><meta name=generator content="makeinfo 4.0"><link href="http://texinfo.org/" rel=generator-home></head><body><p><hr>Node:<a name="Top">Top</a>,Next:<a rel=next href="#Basic%20Aims">Basic Aims</a>,Previous:<a rel=previous href="#(dir)">(dir)</a>,Up:<a rel=up href="#(dir)">(dir)</a><br><h1>Libnet documentation</h1><p>This is the main documentation for Libnet. Most of it is relevant toend-users, but some of it is more relevant to driver authors. Youshould read the instructions in <code>readme.txt</code> before this.<p>All parts of Libnet are Copyright © 1997-1999 Chad Catlettand George Foot.<p>This is edition 10 of the Libnet documentation, consistent with Libnetversion 0.10.2.<ul><li><a href="#Basic%20Aims">Basic Aims</a>: Aims of this project<li><a href="#Functions">Functions</a>: List of functions with descriptions<li><a href="#Drivers">Drivers</a>: Notes on Libnet's drivers<li><a href="#Configuration">Configuration</a>: How to use config files<li><a href="#Structs">Structs</a>: Notes on Libnet's structs<li><a href="#Improvements">Improvements</a>: Future improvements to the library<li><a href="#Contacting%20the%20Authors">Contacting the Authors</a>: How to contact the authors<li><a href="#Mailing%20List">Mailing List</a>: Information about the netgame list<p></p><li><a href="#Variable%2fmacro%20Index">Variable/macro Index</a>: <li><a href="#Concept%20Index">Concept Index</a>: </ul><p><hr>Node:<a name="Basic%20Aims">Basic Aims</a>,Next:<a rel=next href="#Functions">Functions</a>,Previous:<a rel=previous href="#Top">Top</a>,Up:<a rel=up href="#Top">Top</a><br><h1>1. Basic Aims</h1><p>Aims of this project:<ul><li>Make a generic interface to a variety of network drivers.<p>Such an interface will enable people to write programs withnetworking capabilities without having to tie them down toparticular types of network. The same program code will beable to use any supported network (e.g. Winsock, IPX,serial, ...) neither becoming cluttered nor requiring mucheffort to adapt.</p><li>Offer basic functionality only.<p>Restricting the functionality means that more classes ofnetwork can be implemented and makes it easy for new usersto get used to.</p><li>Make addition of new drivers painless.<p>Naturally, writing a new driver will require an amount ofresearch and testing; however, adding new drivers to thelibrary should not be a painful process.</p><li>Start with a core library, and a few sample drivers; inviteother people to contribute new drivers.<p>We can test whether the theory is workable, as well ascreating sample programs to show people how to use thelibrary. Hopefully they will then contribute missingdrivers.</ul><p><hr>Node:<a name="Functions">Functions</a>,Next:<a rel=next href="#Drivers">Drivers</a>,Previous:<a rel=previous href="#Basic%20Aims">Basic Aims</a>,Up:<a rel=up href="#Top">Top</a><br><h1>2. Functions</h1><p>The Libnet library functions fall into the following categories:<ul><li><a href="#Core%20Functions">Core Functions</a>: e.g. initialisation, configuration<li><a href="#Channel%20Functions">Channel Functions</a>: Functions to work with channels<li><a href="#Connection%20Functions">Connection Functions</a>: Functions to work with connections<li><a href="#Driver%20List%20Functions">Driver List Functions</a>: For manipulating driver lists<p></p><li><a href="#Alphabetic%20List%20of%20Functions">Alphabetic List of Functions</a>: </ul><p><hr>Node:<a name="Core%20Functions">Core Functions</a>,Next:<a rel=next href="#Channel%20Functions">Channel Functions</a>,Previous:<a rel=previous href="#Functions">Functions</a>,Up:<a rel=up href="#Functions">Functions</a><br><h2>2.1 Core Functions</h2><p>These functions interact with the core of the library.<ul><li><a href="#net_init">net_init</a>: <li><a href="#net_register_driver">net_register_driver</a>: <li><a href="#net_loadconfig">net_loadconfig</a>: <li><a href="#net_getdrivernames">net_getdrivernames</a>: <li><a href="#net_detectdrivers">net_detectdrivers</a>: <li><a href="#net_initdrivers">net_initdrivers</a>: <li><a href="#net_shutdown">net_shutdown</a>: </ul><p><hr>Node:<a name="net_init">net_init</a>,Next:<a rel=next href="#net_register_driver">net_register_driver</a>,Previous:<a rel=previous href="#Core%20Functions">Core Functions</a>,Up:<a rel=up href="#Core%20Functions">Core Functions</a><br><h3>2.1.1 net_init</h3><h4>Prototype</h4><pre>int net_init (void);</pre><h4>Purpose</h4><p>This function initialises the library, and should be called beforeany others.<h4>Return Value</h4><p>This function returns 0 on success.<p><hr>Node:<a name="net_register_driver">net_register_driver</a>,Next:<a rel=next href="#net_loadconfig">net_loadconfig</a>,Previous:<a rel=previous href="#net_init">net_init</a>,Up:<a rel=up href="#Core%20Functions">Core Functions</a><br><h3>2.1.2 net_register_driver</h3><h4>Prototype</h4><pre>int net_register_driver (int num, NET_DRIVER *driver);</pre><h4>Purpose</h4><p>This function is primarily used internally by Libnet to registerits own drivers, but it is a public function so you can use it tooif you want to register custom drivers.<p>You should register any custom drivers before calling<code>net_loadconfig</code> (see <a href="#net_loadconfig">net_loadconfig</a>); otherwise theywon't get an opportunity to read the config file.<h4>Parameters</h4><p><var>num</var> is a unique reference number. Make sure it is unique! Youcan check this by seeing whether or not a driver in the driver list<code>net_drivers_all</code> has the same number. Values from 0 to<code>NET_DRIVER_USER - 1</code> inclusive are reserved for Libnet'suse. You can use values from <code>NET_DRIVER_USER</code> to<code>NET_DRIVER_MAX - 1</code>. If you specify 0, Libnet will allocate aunique number on your behalf, out of its reserved range (subject toavailability).<p><var>driver</var> is a pointer to the new driver's function table.<h4>Return Value</h4><p>This function returns the number associated with your driver onsuccess, or 0 on failure. (0 is a reserved driver number.)<p><hr>Node:<a name="net_loadconfig">net_loadconfig</a>,Next:<a rel=next href="#net_getdrivernames">net_getdrivernames</a>,Previous:<a rel=previous href="#net_register_driver">net_register_driver</a>,Up:<a rel=up href="#Core%20Functions">Core Functions</a><br><h3>2.1.3 net_loadconfig</h3><h4>Prototype</h4><pre>int net_loadconfig (char *filename);</pre><h4>Purpose</h4><p>This loads a configuration file and invites the various driversto extract information from it. See <a href="#Configuration">Configuration</a>.<h4>Parameters</h4><p><var>filename</var> can be <code>NULL</code>, a directory name, or a filename(with or without an explicit directory).<p>If <var>filename</var> is <code>NULL</code> the file <code>libnet.cfg</code> isread from the program's home directory (as in <code>argv[0]</code>). If<var>filename</var> is a directory then the file <code>libnet.cfg</code>is loaded from that directory. If <var>filename</var> names a file,that file is loaded.<h4>Return Value</h4><p>This function returns 0 on success. Other return values:<dl><br><dt>1<dd>The resulting filename (i.e. after mangling as above) could notbe statted. The <code>errno</code> variable should be set, so you canuse <code>perror</code> or make comparisons yourself.<br><dt>2<dd>The file could not be opened. More than likely this is an accessproblem, but maybe you ran out of file handles. Again, use<code>errno</code> and/or <code>perror</code> to find out why.</dl><h4>Example</h4><pre>if (net_loadconfig(NULL)) { perror("Error loading config file"); exit (1);}</pre><p><hr>Node:<a name="net_getdrivernames">net_getdrivernames</a>,Next:<a rel=next href="#net_detectdrivers">net_detectdrivers</a>,Previous:<a rel=previous href="#net_loadconfig">net_loadconfig</a>,Up:<a rel=up href="#Core%20Functions">Core Functions</a><br><h3>2.1.4 net_getdrivernames</h3><h4>Prototype</h4><pre>NET_DRIVERNAME *net_getdrivernames (NET_DRIVERLIST which);</pre><h4>Purpose</h4><p>This function gets the names of some or all of the drivers.<h4>Parameters</h4><p>The <var>which</var> parameter specifies which drivers to query. Thetype <code>NET_DRIVERLIST</code> is defined in <code>libnet.h</code>. You caneither pass a list you created yourself using the driver listfunctions (see <a href="#Driver%20List%20Functions">Driver List Functions</a>), or the list<code>net_drivers_all</code> which contains all the drivers.<h4>Return value</h4><p>This function returns a pointer to an array of <code>NET_DRIVERNAME</code>structs which contain the reference numbers and names of thedrivers specified by <var>which</var>, plus the <code>nonet</code> driverand a terminating entry with a <code>NULL</code> pointer for the drivername. This list is malloced, and should be freed by the caller.<h4>Example</h4><pre>NET_DRIVERNAME *names;int i;NET_DRIVERLIST drivers;/* Get names of all drivers */names = net_getdrivernames (net_drivers_all);/* Print all entries in the array */for (i = 0; names[i].name; i++) printf ("%d: %s\n", names[i].num, names[i].name);/* Free the array */free (names);/* Get names of the Unix sockets and the Winsock driver driver *//* So, first make a list containing them... */drivers = net_driverlist_create(); /* creates empty list */net_driverlist_add (drivers, NET_DRIVER_SOCKS); /* adds sockets driver */net_driverlist_add (drivers, NET_DRIVER_WSOCK_WIN); /* adds Winsock driver *//* ... and then pass it to the function */names = net_getdrivernames (drivers);/* Print the names, as before, and free them */for (i = 0; names[i].name; i++) printf ("%d: %s\n", names[i].num, names[i].name);free (names);/* We don't need the driver list any more */net_driverlist_destroy (drivers);</pre><p>For more real-life examples please refer to the test programs<code>tests/getdrvnm.c</code> and <code>tests/gentest.c</code>, and theclient-server chat example in <code>examples/chat</code>, where both<code>client.c</code> and <code>server.c</code> use this function in a usefulway.<p><hr>Node:<a name="net_detectdrivers">net_detectdrivers</a>,Next:<a rel=next href="#net_initdrivers">net_initdrivers</a>,Previous:<a rel=previous href="#net_getdrivernames">net_getdrivernames</a>,Up:<a rel=up href="#Core%20Functions">Core Functions</a><br><h3>2.1.5 net_detectdrivers</h3><h4>Prototype</h4><pre>NET_DRIVERLIST net_detectdrivers (NET_DRIVERLIST which);</pre><h4>Purpose</h4><p>This function detects whether or not the given drivers canbe used.<h4>Parameters</h4><p><var>which</var> is a driver list, as for <code>net_getdrivernames</code> - see<a href="#net_getdrivernames">net_getdrivernames</a>, and also <a href="#Driver%20List%20Functions">Driver List Functions</a>. Itindicates which drivers to try to detect. <code>net_drivers_all</code>can be given to detect all drivers.<h4>Return value</h4><p>The function returns a similar type showing which of thespecified drivers were actually detected. Note that if youcall this function several times (e.g. once for each driveryou want to detect) its return value only shows which of thedrivers you specified in <var>which</var> were detected; it doesnot include drivers detected on previous calls. Thiscontrasts with the behaviour of <code>net_initdrivers</code>(see <a href="#net_initdrivers">net_initdrivers</a>).<p>Note that the return value is valid only until the next callto this function (or until you shut down the library, ofcourse). You don't need to destroy this list manually.<h4>Example</h4><pre>NET_DRIVERLIST drivers;NET_DRIVERNAME *names;int i;drivers = net_detectdrivers (net_drivers_all);names = net_getdrivernames (drivers);for (i = 0; names[i].name; i++) printf ("%d: %s\n", names[i].num, names[i].name);free (names);</pre><p><hr>Node:<a name="net_initdrivers">net_initdrivers</a>,Next:<a rel=next href="#net_shutdown">net_shutdown</a>,Previous:<a rel=previous href="#net_detectdrivers">net_detectdrivers</a>,Up:<a rel=up href="#Core%20Functions">Core Functions</a><br><h3>2.1.6 net_initdrivers</h3><h4>Prototype</h4><pre>NET_DRIVERLIST net_initdrivers (NET_DRIVERLIST which);</pre><h4>Purpose</h4><p>This function operates similarly to the <code>net_detectdrivers</code>function (see <a href="#net_detectdrivers">net_detectdrivers</a>), but it initialises thespecified drivers rather than detecting them.<h4>Parameters</h4><p><var>which</var> is a driver list as in <code>net_detectdrivers</code>(see <a href="#net_detectdrivers">net_detectdrivers</a>), indicating which drivers to attemptto initialise. <code>net_drivers_all</code> can be given to initialiseall drivers. Drivers will not be initialised unless they weredetected in a previous call to <code>net_detectdrivers</code>. Previouslyinitialised drivers will not be reinitialised.<h4>Return value</h4><p>The function returns a list in the same format as itsargument, just as <code>net_detectdrivers</code> does. Note that itreturns the complete list of initialised (i.e. ready-for-use)drivers, not just those you specified in the call. Again, don'tdestroy or modify this list. It is valid until the next call tothis function only.<h4>Example</h4><pre>NET_DRIVERNAME *names;NET_DRIVERLIST drivers, detected, initialised;⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -