Network Functions
v3NetOpenSyntax#include "cosmnet.h" s32 v3NetOpen( v3_NET * net, u32 host, u16 port, u32 my_host, u16 my_port, u32 mode, u32 firehost, u16 fireport, ascii * firepass ); #define _V3_NETOPEN( net, host, port ) \ v3NetOpen( net, host, port, 0, 0, V3_NET_MODE_TCP, 0, 0, NULL ) DescriptionOpen a network connection to the remote host and port. my_host and my_port are the host and port you attempt to connect from, 0 for either means the OS picks. If mode is V3_NET_MODE_TCP, TCP protocol is used. If mode is V3_NET_MODE_UDP, UDP protocol is used. firehost, fireport, firepass are for proxies that need to go through a firewall. Use semi-colon to separate username from password for socks5 firewall. ONLY proxies will ever cross firewalls. Since v3NetOpen is rather complex, a macro for simpler cases is also defined. _V3_NETOPEN(...) allows just the first 3 parameters to be specified for when you do not need to worry about firewalls and just need a TCP connection. Return ValuesV3_PASS on success, or an error code on failure. Errors
Exampleu32 ip; s32 result; v3_NET * net, * net2; /* ... */ result = v3NetOpen( net, ip, 80, 0, 0, V3_NET_MODE_TCP, 0, 0, NULL); if ( result == V3_PASS ) v3PrintA( "Connection to port 80 established.\n" ); else v3PrintA( "Connection to port 80 failed.\n" ); /* same thing with macro */ result = _V3_NETOPEN( net2, ip, 80 ); if ( result == V3_PASS ) v3PrintA( "Another connection to port 80 established.\n" ); else v3PrintA( "Another connection to port 80 failed.\n" ); v3NetSendSyntax#include "cosmnet.h" s32 v3NetSend( v3_NET * net, const void * data, u32 length ); DescriptionSend the data over the network connection. Returns once data is sent. Connection must be opened/accepted in V3_NET_MODE_TCP mode. Return ValuesV3_PASS on success, or an error code on failure. Errors
Examples32 result; v3_NET * net; ascii to_send[30]; /* ... */ v3StrCopy( to_send, "Hello world!\n", v3u64u32( 30 ) ); result = v3NetSend( net, to_send, v3u32u64( v3StrLengthA( to_send ) ) ); if ( result == V3_PASS ) v3PrintA( "String sent to remote host\n" ); else v3PrintA( "Failed to send the string\n" ); v3NetRecvSyntax#include "cosmnet.h" u32 v3NetRecv( void * buffer, u32 length, v3_NET * net, u32 wait_ms ); DescriptionRead whatever data is available, up to length bytes, into the buffer. If wait_ms is non-zero, then delay up to wait_ms milliseconds until length bytes have been received. Connection must be opened/accepted in V3_NET_MODE_TCP mode. A suggested time for wait_ms is ( length + 5000 ), giving 5 seconds plus 1sec/KB of data allowing for enough data transfer time over modems and other net glitches. Return Valueslength on success, 0 or less than length indicates failure (last_error of net will be set to an error code). ErrorsUpon failure last_error of net will be set to one of the following:
Exampleu32 bytesreceived; v3_NET * net; ascii getbuff[1024]; /* ... */ while ( net->last_error != V3_NET_ERROR_CLOSED ) { bytesreceived = v3NetRecv( getbuff, 1024, net, 1024 + 5000 ); getbuff[bytesreceived] = 0; v3PrintA( "%s", getbuff ); } v3printA( "\nThe remote host closed the connection.\n" ); v3NetSendUDPSyntax#include "cosmnet.h" s32 v3NetSendUDP( v3_NET * net, const void * data, u32 length ); DescriptionSend the data over the network connection. Connection must be opened/listening in V3_NET_MODE_UDP mode. Return ValuesV3_PASS on success, or an error code on failure. Errors
Examplev3NetRecvUDPSyntax#include "cosmnet.h" u32 v3NetRecvUDP( void * buffer, u32 length, v3_NET * net, v3_NET_ACL * acl, u32 wait_ms ); DescriptionRead whatever data is available, up to length bytes, into the buffer. If wait_ms is non-zero, then delay up to wait_ms milliseconds until length bytes have been received. Connection must be opened/listening in V3_NET_MODE_UDP mode. Any data from a host that fails the acl masks will be discarded. Return Valueslength on success, 0 or less than length indicates failure (last_error of net will be set to an error code). ErrorsUpon failure last_error of net will be set to one of the following:
Examplev3NetListenSyntax#include "cosmnet.h" s32 v3NetListen( v3_NET * net, u32 ip, u16 port, u32 mode, u32 queue ); DescriptionSet up a listening point on port that will accept connections. Listen on ip if possible, if ip is zero listen on all interfaces. If mode is V3_NET_MODE_TCP, TCP protocol is used. If mode is V3_NET_MODE_UDP, then the UDP protocol is used. If port is zero, let OS pick one. Allow queue connections to be queued before rejecting connections. Return ValuesV3_PASS on success, or an error code on failure. Errors
Examples32 result; v3_NET * net; result = v3NetListen( net, 0, 5150, V3_NET_MODE_TCP, 5 ); if ( result == V3_PASS ) v3PrintA( (ascii *) "Listening on port 5150 on all interfaces.\n" ); else v3PrintA( (ascii *) "Couldn't bind to port 5150. Is the port in use?\n" ); v3NetAcceptSyntax#include "cosmnet.h" s32 v3NetAccept( v3_NET * new_connection, v3_NET * net, v3_NET_ACL * acl, u32 wait ); DescriptionAccept a network connection if one is waiting, and fill in all the fields of new_connection. If wait is V3_NET_ACCEPT_WAIT then do not return until a connection is accepted, otherwise if wait is V3_NET_ACCEPT_NOWAIT return immediately. Any host that fails the acl masks will be ignored. Return ValuesV3_PASS on success, or an error code on failure. Errors
Examples32 result; v3_NET * net; v3_NET * connection; v3NetListen( net, 0, 5150, 5 ); /* ... */ result=v3NetAccept( connection, net, NULL, V3_NET_ACCEPT_NOWAIT ); if ( result == V3_PASS ) v3PrintA( "Connection received to port 5150.\n" ); else v3PrintA( "Nobody is waiting to connect on port 5150.\n" ); v3NetCloseSyntax#include "cosmnet.h" s32 v3NetClose( v3_NET * net ); DescriptionClose the Network connection and clear out any remaining data. Return ValuesV3_PASS on success, or an error code on failure. Errors
Examples32 result; v3_NET * net; /* ... */ result = v3NetClose( net ); if ( result == V3_PASS ) v3PrintA( "Connection closed and remaining data flushed.\n" ); else v3PrintA( "The remote host closed the connection before us.\n" ); v3NetDNSSyntax#include "cosmnet.h" u32 v3NetDNS( u32 * ip, u32 length, ascii * name ); DescriptionPerform DNS lookup. Sets up to length ip's to the IP of the name'd host. Return ValuesNumber of IP's set, 0 indicates failure. ErrorsPossible causes of failure:
Exampleu32 hosts[16]; u32 result; result = v3NetDNS( &host, 16, "cosm.mithral.com" ); if ( result > 0 ) v3PrintA( "Hostname cosm.mithral.com successfully resolved.\n" ); else v3PrintA( "Error resolving host cosm.mithral.com.\n" ); v3NetRevDNSSyntax#include "cosmnet.h" s32 v3NetRevDNS( v3_NET_HOSTNAME * name, u32 ip ); DescriptionPerform reverse DNS. Sets name to the hostname of the ip. Return ValuesV3_PASS on success, or V3_FAIL on failure. ErrorsPossible causes of failure:
Examples32 result; u32 ip; v3_NET_HOSTNAME hostname; ip = 0xD162B486; result = v3NetRevDNS( hostname, ip ); if ( result == V3_PASS ) v3PrintA( (ascii *) hostname ); else v3PrintA( "Unable to perform reverse DNS.\n" ); v3NetMyIPSyntax#include "cosmnet.h" s32 v3NetMyIP( u32 * ip ); DescriptionSets ip to the hosts IP. Return ValuesV3_PASS on success, or V3_FAIL on failure. ErrorsPossible causes of failure:
Examples32 result; u32 host; result = v3NetMyIP( &host ); if ( result == V3_PASS ) v3PrintA( "Local IP address successfully determined.\n" ); else v3PrintA( "Unable to determine local IP address.\n" ); v3NetACLAddSyntax#include "cosmnet.h" s32 v3NetACLAdd( v3_NET_ACL * acl, u32 ip, u32 mask, u32 permission, v3_time expires ); DescriptionAdd the ip/mask pair to the acl. permission should be either V3_NET_ALLOW or V3_NET_DENY. expires is the time after which the entry will be deleted automatically, and should be based off of v3SystemClock time. Return ValuesV3_PASS on success, or V3_FAIL on failure. ErrorsExamplev3NetACLDeleteSyntax#include "cosmnet.h" s32 v3NetACLDelete( v3_NET_ACL * acl, u32 ip, u32 mask ); DescriptionDelete the ip/mask entry from the acl. Return ValuesV3_PASS on success, or V3_FAIL on failure. ErrorsExamplev3NetACLTestSyntax#include "cosmnet.h" s32 v3NetACLTest( v3_NET_ACL * acl, u32 ip ); DescriptionTest if an ip is accepted by the acl. An ip is accepted if it passed through each of the acl entries in order and has a V3_NET_ALLOW setting at the end. The default is to allow (a NULL or empty acl). Return ValuesV3_NET_ALLOW if accepted, or V3_NET_DENY if rejected. ErrorsExamplev3NetACLFreeSyntax#include "cosmnet.h" void v3NetACLFree( v3_NET_ACL * acl ); DescriptionFree the internal acl data. Return ValuesNone. ErrorsExample
© Copyright Mithral Communications & Design, Inc. 1999.
All rights reserved.
Mithral(tm) and Cosm(tm) are trademarks of
Mithral Communications & Design, Inc.
|