[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: