[Cosm Logo]

Network Functions


v3NetOpen

Syntax

#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 )

Description

Open 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 Values

V3_PASS on success, or an error code on failure.

Errors

V3_NET_ERROR_HOST
Unable to connect to host.
V3_NET_ERROR_PORT
Unable to connect/listen on port.
V3_NET_ERROR_FIREHOST
Invalid firewall host.
V3_NET_ERROR_FIREPORT
Invalid firewall port.
V3_NET_ERROR_FIREPASS
Bad firewall password.
V3_NET_ERROR_CLOSED
Connection closed.
V3_NET_ERROR_NO_NET
No networking support.

Example

  u32 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" );


v3NetSend

Syntax

#include "cosmnet.h"
s32 v3NetSend( v3_NET * net, const void * data, u32 length );

Description

Send the data over the network connection. Returns once data is sent. Connection must be opened/accepted in V3_NET_MODE_TCP mode.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_NET_ERROR_HOST
Unable to connect to host.
V3_NET_ERROR_CLOSED
Connection closed.
V3_NET_ERROR_NO_NET
No networking support.

Example

  s32 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" );

v3NetRecv

Syntax

#include "cosmnet.h"
u32 v3NetRecv( void * buffer, u32 length, v3_NET * net, u32 wait_ms );

Description

Read 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 Values

length on success, 0 or less than length indicates failure (last_error of net will be set to an error code).

Errors

Upon failure last_error of net will be set to one of the following:

V3_NET_ERROR_HOST
Unable to connect to host.
V3_NET_ERROR_CLOSED
Connection closed.
V3_NET_ERROR_NO_NET
No networking support.

Example

  u32 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" );

v3NetSendUDP

Syntax

#include "cosmnet.h"
s32 v3NetSendUDP( v3_NET * net, const void * data, u32 length );

Description

Send the data over the network connection. Connection must be opened/listening in V3_NET_MODE_UDP mode.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_NET_ERROR_NO_NET
No networking support.

Example




    

v3NetRecvUDP

Syntax

#include "cosmnet.h"
u32 v3NetRecvUDP( void * buffer, u32 length, v3_NET * net, v3_NET_ACL * acl,
  u32 wait_ms );

Description

Read 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 Values

length on success, 0 or less than length indicates failure (last_error of net will be set to an error code).

Errors

Upon failure last_error of net will be set to one of the following:

V3_NET_ERROR_NO_NET
No networking support.

Example




    

v3NetListen

Syntax

#include "cosmnet.h"
s32 v3NetListen( v3_NET * net, u32 ip, u16 port, u32 mode, u32 queue );

Description

Set 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 Values

V3_PASS on success, or an error code on failure.

Errors

V3_NET_ERROR_PORT
Unable to connect/listen on port.
V3_NET_ERROR_NO_NET
No networking support.

Example

  s32 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" );

v3NetAccept

Syntax

#include "cosmnet.h"
s32 v3NetAccept( v3_NET * new_connection, v3_NET * net, v3_NET_ACL * acl,
  u32 wait );

Description

Accept 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 Values

V3_PASS on success, or an error code on failure.

Errors

V3_NET_ERROR_CLOSED
Connection closed.
V3_NET_ERROR_NO_NET
No networking support.

Example

  s32 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" );

v3NetClose

Syntax

#include "cosmnet.h"
s32 v3NetClose( v3_NET * net );

Description

Close the Network connection and clear out any remaining data.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_NET_ERROR_CLOSED
Connection closed.
V3_NET_ERROR_NO_NET
No networking support.

Example

  s32 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" );

v3NetDNS

Syntax

#include "cosmnet.h"
u32 v3NetDNS( u32 * ip, u32 length, ascii * name );

Description

Perform DNS lookup. Sets up to length ip's to the IP of the name'd host.

Return Values

Number of IP's set, 0 indicates failure.

Errors

Possible causes of failure:

  • ip or name is NULL.
  • length is 0.
  • Couldn't get the IP of the name'd host.

Example

  u32 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" );

v3NetRevDNS

Syntax

#include "cosmnet.h"
s32 v3NetRevDNS( v3_NET_HOSTNAME * name, u32 ip );

Description

Perform reverse DNS. Sets name to the hostname of the ip.

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

Possible causes of failure:

  • name is NULL.
  • ip is 0.
  • Can't get a domain name for ip.

Example

  s32 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" );

v3NetMyIP

Syntax

#include "cosmnet.h"
s32 v3NetMyIP( u32 * ip );

Description

Sets ip to the hosts IP.

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

Possible causes of failure:

  • ip is NULL.
  • Couldn't get local host name.
  • Couldn't get IP of local host name.

Example

  s32 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" );

v3NetACLAdd

Syntax

#include "cosmnet.h"
s32 v3NetACLAdd( v3_NET_ACL * acl, u32 ip, u32 mask, u32 permission,
  v3_time expires );

Description

Add 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 Values

V3_PASS on success, or V3_FAIL on failure.

Errors

Example




    

v3NetACLDelete

Syntax

#include "cosmnet.h"
s32 v3NetACLDelete( v3_NET_ACL * acl, u32 ip, u32 mask );

Description

Delete the ip/mask entry from the acl.

Return Values

V3_PASS on success, or V3_FAIL on failure.

Errors

Example




    

v3NetACLTest

Syntax

#include "cosmnet.h"
s32 v3NetACLTest( v3_NET_ACL * acl, u32 ip );

Description

Test 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 Values

V3_NET_ALLOW if accepted, or V3_NET_DENY if rejected.

Errors

Example




    

v3NetACLFree

Syntax

#include "cosmnet.h"
void v3NetACLFree( v3_NET_ACL * acl );

Description

Free the internal acl data.

Return Values

None.

Errors

Example





© Copyright Mithral Communications & Design, Inc. 1999. All rights reserved. Mithral(tm) and Cosm(tm) are trademarks of Mithral Communications & Design, Inc.
Document last modified: