[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,
  const ascii * firepass );

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: 

s32 _V3_NETOPEN( v3_NET * net, u32 host, u16 port );

_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, u32 * bytes_sent, const void * data,
  u32 length );

Description

Send the data over the network connection. Returns once data is sent. bytes_sent is set to the number of bytes actually 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];
  u32 bytes;

  /* ... */

  v3StrCopy( to_send, "Hello world!\n", v3u64u32( 30 ) );
  result = v3NetSend( net, &bytes, to_send,
    v3u32u64( v3StrLengthA( to_send ) ) );
  if ( result == V3_PASS )
  {
    v3PrintA( "String sent to remote host\n" );
  }
  else
  {
    v3PrintA( "Sent %u bytes of string\n", bytes );
  }

v3NetRecv

Syntax

 
#include "cosmnet.h"
s32 v3NetRecv( void * buffer, u32 * bytes_received, v3_NET * net,
  u32 length, 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. bytes_received is set to the number of bytes actually read. 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

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

 
  u32 bytes;
  v3_NET * net;
  ascii getbuff[1024];

  /* ... */

  while ( v3NetRecv( getbuff, &bytes, net, 1024,
    1024 + 5000 ) == V3_PASS )
  {
    getbuff[bytes] = 0;
    v3PrintA( "%s", getbuff );
  }
  v3printA( "\nThe remote host closed the connection.\n" );

v3NetSendUDP

Syntax

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

Description

Send length bytes of data to the host and port, may or may not arrive. 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"
s32 v3NetRecvUDP( void * buffer, u32 * bytes_read, v3_NET * net, u32 length,
  v3_NET_ACL * acl, u32 wait_ms );




    
Description

    

      Read a UDP packet into the buffer, if the buffer length is
      not long enough to hold the packet, the remaining data will be lost.
      If wait_ms is non-zero, then delay up to wait_ms
      milliseconds for a packet to arrive. Connection must be
      opened/listening in V3_NET_MODE_UDP mode. Any data from a host that
      fails the acl masks will be ignored.
    


    
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, the OS may silently limit this number.
    


    
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_PARAM
      
Parameter error.
      
V3_NET_ERROR_TIMEOUT
      
No waiting connection.
      
V3_NET_ERROR_CLOSED
      
Connection closed.
      
V3_NET_ERROR_SOCKET
      
Internal socket error, now closed.
      
V3_NET_ERROR_MODE
      
UDP accepts not allowed.
      
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( &hosts, 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.
    
    1995-2005.
    All rights reserved.
    Mithral® and Cosm® are trademarks of
    Mithral Communications & Design Inc.
    

    
    Document last modified: Jun 16, 2005