v0.3 - 2007.06.26
Coded by Ian Seyler (iseyler@gmail.com)
http://bubbai.ath.cx/projects/netlib/
The latest documentation is available online at http://bubbai.ath.cx/projects/netlib/manual.html
netLib was verified to work with different versions of the GCC compiler. Tested OS's were Windows (2000, XP, and Vista), Mac OS X (10.3 and 10.4), BeOS 5, *BSD (OpenBSD 3.8), and Linux (Fedora 7, Ubuntu 7.04, and Debian 4.0).
Make sure to include netLib.h in the yournetapp.c source file.
gcc yournetapp.c netLib.c -o yournetapp -DMS_WINDOWS -L../lib/win32 -lwsock32
This is used for all unix-based systems (Mac OS X, Linux, FreeBSD, etc).
gcc yournetapp.c netLib.c -o yournetapp -DUNIX
Note: netLib currently does not function using BONE and has not been testing with Haiku.
gcc yournetapp.c netLib.c -o yournetapp -DBEOS
With an additional flag to the compiler you can set the verbose option. By default, the library is set to a silent mode (Verbose level 0). Verbose level 1 will show the function names as they run as well as any error messages. Verbose level 2 shows the same messages as level 1 in addition to debugging information.
-DnlVerbose=1
These two main structures are used by the netLib fuctions. The variables in these functions are modified by the netLib functions and should not be modified directly by the user.
struct netSocketStruct {
int number; // the socket descriptor from the socket() call
int inuse; // 1 for active, 0 for not active
int retval; // all functions will update this variable with the function return value
struct timeval timeout; // timeout value
struct sockaddr_in addr; // connector's address information
};
number : The internal number of the socket
inuse : A boolean value for indicating wether the socket is in use (connected) or not. 1 is active.
retval : Whenever a netLib function is run on the socket it will place the return value here.
timeout : This is the timeout value for the socket. The default value is 0.1 seconds but it can be changed with netSetTimeout.
addr : The internal values for the socket.
Example:
netSocket *clientsocket[15]; // create an array of 15 netSockets
struct netBufferStruct {
int size; // size in bytes of data
int at; // location in data where we are currently when reading and writing
char complete; // set to 1 when we have completed the buffer
char *data; // pointer to the data
};
size : The size of the data buffer. This value should not be changed after the netInitBuffer is run.
at : The current location in the buffer that we are writing to or reading from.
complete : A boolean value for indicating wether or not the buffer is complete. 1 is complete.
*data : A pointer to where the data is located in memory.
Example:
netBuffer *databuffer; // create a netBuffer
This list contains the netLib functions, along with a short description and example of each.
int netInit (); Entry : nothing Returns : 0 on success, -1 on failure
Initiate the netLib library. This function runs extra code to start Winsock, if it is being run on a Windows-based machine.
Example:
netInit();
int netStop (); Entry : nothing Returns : 0 on success, -1 on failure
Stop the netLib library. This function runs extra code to stop Winsock if it is being run on a Windows-based machine.
Example:
netStop();
netSocket* netInitSocket (); Entry : nothing Returns : a pointer to a netSocket, NULL on error
Initiate a new netSocket. Note that all netSockets are pointers. You must initialize the netSocket before using it!
Example:
netSocket *tempsocket; // create a netSocket tempsocket = netInitSocket(); // Initialize the netSocket. Initialization is required!!
netBuffer* netInitBuffer (int size); Entry : int size = The size in bytes of the buffer Returns : a pointer to a netBuffer, NULL on error
Initiate a new netBuffer. Note that all netBuffers are pointers. You must initialize the netBuffer before using it!
Example:
netBuffer *tempbuffer; // create a netBuffer tempbuffer = netInitBuffer(128); // Initialize a 128 byte netBuffer. Initialization is required!!
int netConnect(netSocket *netSock, char *address, unsigned short port);
Entry : netSocket *netSock = Socket to connect
char *address = Character string of the destination (eg: "bubbai.ath.cx" or "192.168.0.1")
unsigned short port = The port on the destination to connect to
Returns : 0 on success, -1 on failure
Connect a netSocket to the specified destination. The second argument is the destination. This can be a name or an IP address. The second argument is the destination port. The computer you are connecting to must be listening on this port.
Example:
if (netConnect(tempsocket, "bubbai.ath.cx", 80) == netOK) // Connects tempsocket to bubbai.ath.cx on port 80
printf("Connection Sucessful!");
else
printf("Error: Could not connect to host.");
int netDisconnect (netSocket *netSock); Entry : netSocket *netSock = The socket to disconnect Returns : 0 on success, -1 on failure
Disconnect a netSocket.
Example:
netDisconnect(tempsocket);
int netListen (netSocket *netSock, unsigned short port);
Entry : netSocket *netSock = Socket to listen on
unsigned short port = Port number to listen on
Returns : 0 on success, -1 on failure
Listen on a specified netSocket.
Example:
netListen(listensocket, 8192); // Set the netSocket to listen on port 8192
int netAccept (netSocket *listenSock, netSocket *netSock);
Entry : netSocket *listenSock = The listening socket
netSocket *netSock = The netSocket that has just connected
Returns : 1 on an accepted connection, 0 on nothing to accept, -1 on error
Accept a connection from a listening port. netAccept returns a valid open connection to the netSocket in the second argument.
Example:
netAccept(listensocket, tempsocket); // Accept a connection from the listening netSocket
int netIsDataPending (netSocket *netSock); Entry : netSocket *netSock = The socket to check Returns : 1 if data is pending, 0 if no data is pending
Checks if a netSocket is waiting for action. This command will give a return value of 0 if the socket is not waiting, and a value of 1 if the socket is waiting.
Example:
if (netIsDataPending(tempsocket) == 1) // Checks if tempsocket has data that is pending to be read
printf("The socket has data");
else
printf("The socket has no data");
int netSend (netSocket *netSock, char *data, int bytes);
Entry : netSocket *netSock = Socket to send data to
char *data = Pointer to a character string, this is the data that will be transfered
int bytes = the number of bytes to send starting at *data
Returns : number of bytes that were sent, -1 on error
Send a number of bytes to a netSocket.
Example:
netSend(tempsocket, "Hello, World!\0", 14); // Sends the 14 byte message to tempsocket
int netRecv (netSocket *netSock, char *data, int bytes);
Entry : netSocket *netSock = Socket to receive data from
char *data = Pointer to a character string, this is where the data will be stored
int bytes = the number of bytes to receive
Returns : number of bytes that were received, -1 on error
Receive a number of bytes from a netSocket. Puts the received data into the string data. Make sure you have enough room.
Example:
netRecv(tempsocket, string, 14); // Reads 14 bytes from tempsocket and places the data into string
int netSendBuffer (netSocket *netSock, netBuffer *netBuff);
Entry : netSocket *netSock = The socket to send to
netBuffer *netBuff = The buffer to be sent out
Returns : number of bytes that were sent, -1 on error
Send data from a netBuffer to a netSocket. netSendBuffer will send the entire buffer unless an error occurs.
Example:
netSendBuffer(tempsocket, tempbuffer); // Sends the netBuffer tempbuffer to tempsocket
int netRecvBuffer (netSocket *netSock, netBuffer *netBuff);
Entry : netSocket *netSock = The socket to receive from
netBuffer *netBuff = The buffer where the incoming data will be stored
Returns : number of bytes that were received, -1 on error
Receive data from a netSocket to a netBuffer. netRecvBuffer will receive the entire buffer unless an error occurs.
Example:
netRecvBuffer(tempsocket, tempbuffer); // Receives the netBuffer tempbuffer from tempsocket
int netSetTimeout (netSocket *netSock, float timeoutvalue);
Entry : netSocket *netSock = The socket to set
float timeoutvalue = The new timeout value
Returns : 0 on success, -1 on failure
Sets the timeout value on a netSocket. timeoutvalue is given in seconds.
Example:
netSetTimeout(tempsocket, 1.0); // Sets the timout on tempsocket to one second
These two sample programs are very simple demos of netLib. These simple examples do not do any error checking.
/* A simple server for netLib. */
#include "netLib.h"
void main()
{
netSocket *listensocket, *clientsocket;
netInit(); // Start the netLib library
listensocket = netInitSocket();
clientsocket = netInitSocket();
netListen(listensocket, 8123); // Set the server to listen on port 8123
while(netAccept(listensocket, clientsocket) != 1)
{
printf("\nWaiting for client...");
}
netSend(clientsocket, "Testing 1..2..3..\0", 18);
netDisconnect(clientsocket);
netDisconnect(listensocket);
netStop();
}
/* A simple client for netLib. */
#include "netLib.h"
void main()
{
netSocket *serversocket;
char incomingdata[20];
netInit(); // Start the netLib library
serversocket = netInitSocket();
netConnect(serversocket, "127.0.0.1", 8123); // Assume server is running on same machine
netRecv(serversocket, incomingdata, 18);
printf("\nGot '%s' from server", incomingdata);
netDisconnect(serversocket);
netStop();
}
The Chat program was written using netLib for all network-related communication. The chat server is able to support multiple simultaneous client connections. Full source code is included with the netLib distribution.
The chat server does not require any arguments. Just start the executable. The chat server will wait for incoming client connections and accept messages from them. It will then send these messages to the other connected clients.
chatserver «ENTER» Chat Server v0.1 (A demo using netLib) Designed and coded by Ian Seyler netLib: Start Windows networking (v0.3)
The chat client must be started twice, once for the listening mode window (to see what other users are typing) and once for the speaking mode window (so you can type to the other clients). The arguments for chat are "chat hostname [-listen or -speak]" where hostname is the name or IP address of the chat server. In the following examples "localhost" is used as the chat server is running on the local computer.
For listen mode:
chat localhost -l «ENTER» Chat v0.1 (A demo using netLib) Designed and coded by Ian Seyler netLib: Start Windows networking (v0.3) Listen mode Connecting to chat server... OK!
For speak mode:
chat localhost -s «ENTER» Chat v0.1 (A demo using netLib) Designed and coded by Ian Seyler netLib: Start Windows networking (v0.3) Speak mode Enter your nickname (Max 8 chars): Ian Your nickname is 'Ian' Connecting to chat server... OK! Say:
The server will show a log of client connections and message transfers. You can use Control+C to stop the chat server.
chatserver «ENTER» Chat Server v0.1 (A demo using netLib) Designed and coded by Ian Seyler netLib: Start Windows networking (v0.3) Got a connection. Client is 1 --> Listen mode Got a connection. Client is 2 --> Speak mode : Ian. Sending server message to clients. Got a connection. Client is 3 --> Listen mode Got a connection. Client is 4 --> Speak mode : Caroline. Sending server message to clients. Message received from client 2. Sending message to clients. Message received from client 4. Sending message to clients. Message received from client 2. Sending message to clients. Message received from client 4. Sending message to clients. Message received from client 2. Sending message to clients. Message received from client 4. Sending message to clients. Message received from client 2. Sending message to clients. Message received from client 4. Sending message to clients.^C
Listen mode:
chat localhost -l «ENTER» Chat v0.1 (A demo using netLib) Designed and coded by Ian Seyler netLib: Start Windows networking (v0.3) Listen mode Connecting to chat server... OK! CHANSERV: Ian has joined the chat. CHANSERV: Caroline has joined the chat. Ian : Hello Caroline! Caroline: Hi Ian.. hows it going? Ian : ok.. you? Caroline: I'm pregnant! Ian : cool.. well cya later! Caroline: bye CHANSERV: Ian has left the chat. ^C
Speak mode:
chat localhost -s «ENTER» Chat v0.1 (A demo using netLib) Designed and coded by Ian Seyler netLib: Start Windows networking (v0.3) Speak mode Enter your nickname (Max 8 chars): Ian Your nickname is 'Ian' Connecting to chat server... OK! Say: Hello Caroline! Say: ok.. you? Say: cool.. well cya later! Say: /quit Disconnected from chat server.
Listen mode:
chat localhost -l «ENTER» Chat v0.1 (A demo using netLib) Designed and coded by Ian Seyler netLib: Start Windows networking (v0.3) Listen mode Connecting to chat server... OK! CHANSERV: Caroline has joined the chat. Ian : Hello Caroline! Caroline: Hi Ian.. hows it going? Ian : ok.. you? Caroline: I'm pregnant! Ian : cool.. well cya later! Caroline: bye CHANSERV: Ian has left the chat. CHANSERV: Caroline has left the chat. ^C
Speak mode:
chat localhost -s «ENTER» Chat v0.1 (A demo using netLib) Designed and coded by Ian Seyler netLib: Start Windows networking (v0.3) Speak mode Enter your nickname (Max 8 chars): Caroline Your nickname is 'Caroline' Connecting to chat server... OK! Say: Hi Ian.. hows it going? Say: I'm pregnant! Say: bye Say: /quit Disconnected from chat server.
Last updated Jun 25, 2007 @ 1:39PM