[Cosm Logo]

Network Functions

CosmNetOpen

Syntax

 
#include "cosm/os_net.h"
s32 CosmNetOpen( cosm_NET * net, cosm_NET_ADDR host, u16 port, cosm_NET_ADDR my_host,
  u16 my_port, u32 mode, cosm_NET_ADDR 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 COSM_NET_MODE_TCP, TCP protocol is used. If mode is COSM_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 CosmNetOpen is rather complex, a macro for simpler cases is also defined: 

s32 _COSM_NETOPEN( cosm_NET * net, cosm_NET_ADDR host, u16 port );

_COSM_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

COSM_PASS on success, or an error code on failure.

Errors

COSM_NET_ERROR_HOST
Unable to connect to host.
COSM_NET_ERROR_PORT
Unable to connect/listen on port.
COSM_NET_ERROR_FIREHOST
Invalid firewall host.
COSM_NET_ERROR_FIREPORT
Invalid firewall port.
COSM_NET_ERROR_FIREPASS
Bad firewall password.
COSM_NET_ERROR_CLOSED
Connection closed.
COSM_NET_ERROR_NO_NET
No networking support.

Example

 
  cosm_NET_ADDR ip;
  s32 result;
  cosm_NET * net, * net2;

  /* ... */

  result = CosmNetOpen( net, ip, 80, 0, 0, COSM_NET_MODE_TCP,
    0, 0, NULL);

  if ( result == COSM_PASS )
    CosmPrint( "Connection to port 80 established.\n" );
  else
    CosmPrint( "Connection to port 80 failed.\n" );

  /* same thing with macro */
  result = _COSM_NETOPEN( net2, ip, 80 );

  if ( result == COSM_PASS )
    CosmPrint( "Another connection to port 80 established.\n" );
  else
    CosmPrint( "Another connection to port 80 failed.\n" );

CosmNetSend

Syntax

 
#include "cosm/os_net.h"
s32 CosmNetSend( cosm_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 COSM_NET_MODE_TCP mode.

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_NET_ERROR_HOST
Unable to connect to host.
COSM_NET_ERROR_CLOSED
Connection closed.
COSM_NET_ERROR_NO_NET
No networking support.

Example

 
  s32 result;
  cosm_NET * net;
  ascii to_send[30];
  u32 bytes;

  /* ... */

  CosmStrCopy( to_send, "Hello world!\n", 30LL );
  result = CosmNetSend( net, &bytes, to_send,
    CosmStrBytes( to_send ) );
  if ( result == COSM_PASS )
  {
    CosmPrint( "String sent to remote host\n" );
  }
  else
  {
    CosmPrint( "Sent %u bytes of string\n", bytes );
  }

CosmNetRecv

Syntax

 
#include "cosm/os_net.h"
s32 CosmNetRecv( void * buffer, u32 * bytes_received, cosm_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 COSM_NET_MODE_TCP mode. A suggested time for wait_ms is ( length + 5000 ), giving 5 seconds plus 1sec/KiB of data allowing for enough data transfer time over modems and other net glitches.

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_NET_ERROR_HOST
Unable to connect to host.
COSM_NET_ERROR_CLOSED
Connection closed.
COSM_NET_ERROR_NO_NET
No networking support.

Example

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

  /* ... */

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

CosmNetSendUDP

Syntax

 
#include "cosm/os_net.h"
s32 CosmNetSendUDP( cosm_NET * net, const cosm_NET_ADDR * addr,
  const void * data, u32 length );

Description

Send length bytes of data to the addr, may or may not arrive. Connection must be opened in COSM_NET_MODE_UDP mode.

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_NET_ERROR_NO_NET
No networking support.

Example

 



    


    
    

      CosmNetRecvUDP
    


    
Syntax



#include "cosm/os_net.h"
s32 CosmNetRecvUDP( void * buffer, u32 * bytes_read, cosm_NET * net, u32 length,
  cosm_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
      listening in COSM_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:
    

    

      
COSM_NET_ERROR_NO_NET
      
No networking support.
    


    
Example






    


    
    

      CosmNetListen
    


    
Syntax



#include "cosm/os_net.h"
s32 CosmNetListen( cosm_NET * net, const cosm_NET_ADDR * addr, u32 mode,
  u32 queue );




    
Description

    

      Set up a listening point on addr that will accept connections.
      Listen on addr if possible, if the IP is zero then listen on
      all interfaces. If mode is COSM_NET_MODE_TCP, TCP protocol is used. If
      mode is COSM_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

    

      COSM_PASS on success, or an error code on failure.
    


    
Errors

    

      
COSM_NET_ERROR_PORT
      
Unable to connect/listen on port.
      
COSM_NET_ERROR_NO_NET
      
No networking support.
    


    
Example



  s32 result;
  cosm_NET * net;

  result = CosmNetListen( net, 0, 5150, COSM_NET_MODE_TCP, 5 );

  if ( result == COSM_PASS )
    CosmPrint(
      "Listening on port 5150 on all interfaces.\n" );
  else
    CosmPrint(
      "Couldn't bind to port 5150. Is the port in use?\n" );




    


    
    

      CosmNetAccept
    


    
Syntax



#include "cosm/os_net.h"
s32 CosmNetAccept( cosm_NET * new_connection, cosm_NET * net, cosm_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 COSM_NET_ACCEPT_WAIT then do not return until a
      connection is accepted, otherwise if wait is
      COSM_NET_ACCEPT_NOWAIT return immediately. Any host that fails the
      acl masks will be ignored.
    


    
Return Values

    

      COSM_PASS on success, or an error code on failure.
    


    
Errors

    

      
COSM_NET_ERROR_PARAM
      
Parameter error.
      
COSM_NET_ERROR_TIMEOUT
      
No waiting connection.
      
COSM_NET_ERROR_CLOSED
      
Connection closed.
      
COSM_NET_ERROR_SOCKET
      
Internal socket error, now closed.
      
COSM_NET_ERROR_MODE
      
UDP accepts not allowed.
      
COSM_NET_ERROR_NO_NET
      
No networking support.
    


    
Example



  s32 result;
  cosm_NET * net;
  cosm_NET * connection;

  CosmNetListen( net, 0, 5150, 5 );

  /* ... */

  result=CosmNetAccept( connection, net, NULL, COSM_NET_ACCEPT_NOWAIT );
  if ( result == COSM_PASS )
    CosmPrint( "Connection received to port 5150.\n" );
  else
    CosmPrint( "Nobody is waiting to connect on port 5150.\n" );




    


    
    

      CosmNetClose
    


    
Syntax



#include "cosm/os_net.h"
s32 CosmNetClose( cosm_NET * net );




    
Description

    

      Close the Network connection and clear out any remaining data.
    


    
Return Values

    

      COSM_PASS on success, or an error code on failure.
    


    
Errors

    

      
COSM_NET_ERROR_CLOSED
      
Connection closed.
      
COSM_NET_ERROR_NO_NET
      
No networking support.
    


    
Example



  s32 result;
  cosm_NET * net;

  /* ... */

  result = CosmNetClose( net );
  if ( result == COSM_PASS )
    CosmPrint( "Connection closed and remaining data flushed.\n" );
  else
    CosmPrint( "The remote host closed the connection before us.\n" );




    


    
    

      CosmNetDNS
    


    
Syntax



#include "cosm/os_net.h"
u32 CosmNetDNS( cosm_NET_ADDR * addr, u32 count, ascii * name );




    
Description

    

      Perform DNS lookup. Sets up to count addr's to the
      addresses 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.
      
  • count is 0.
      
  • Couldn't get the IP of the name'd host.
    


    
Example



  cosm_NET_ADDR hosts[16];
  u32 result;

  result = CosmNetDNS( &hosts, 16, "www.mithral.com" );
  if ( result > 0 )
    CosmPrint( "Hostname www.mithral.com successfully resolved.\n" );
  else
    CosmPrint( "Error resolving host www.mithral.com.\n" );




    


    
    

      CosmNetRevDNS
    


    
Syntax



#include "cosm/os_net.h"
s32 CosmNetRevDNS( cosm_NET_HOSTNAME * name, cosm_NET_ADDR ip );




    
Description

    

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


    
Return Values

    

      COSM_PASS on success, or COSM_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;
  cosm_NET_ADDR ip;
  cosm_NET_HOSTNAME hostname;

  ip = 0xD162B486;

  result = CosmNetRevDNS( hostname, ip );
  if ( result == COSM_PASS )
    CosmPrint( hostname );
  else
    CosmPrint( "Unable to perform reverse DNS.\n" );




    


    
    

      CosmNetMyIP
    


    
Syntax



#include "cosm/os_net.h"
u32 CosmNetMyIP( cosm_NET_ADDR * addr, u32 count );




    
Description

    

      Sets up to count addr's to the IP of the host.
      A mix of IPv4 and IPv6 addresses will be returned, and the first
      result will be the "primary" IP of the system. 127.0.0.1 and ::1
      will not be on the list.
    


    
Return Values

    

      Number of addresses set, 0 indicates failure.
    


    
Errors

    

      Possible causes of failure:
    

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


    
Example



  s32 result;
  cosm_NET_ADDR host[8];

  if ( CosmNetMyIP( &host, 8 ) > 0 )
  {
    CosmPrint( "Local addresses successfully determined.\n" );
  }
  else
  {
    CosmPrint( "Unable to determine local addresses.\n" );
  }




    


    
    

      CosmNetACLAdd
    


    
Syntax



#include "cosm/os_net.h"
s32 CosmNetACLAdd( cosm_NET_ACL * acl, cosm_NET_ADDR ip, u32 mask_bits,
  u32 permission, cosmtime expires );




    
Description

    

      Add the ip/mask_bits pair to the acl.
      A mask of 255.255.255.0/24 is 24 mask_bits, 255.255.0.0/16 is 16, etc.
      permission should be either COSM_NET_ALLOW or COSM_NET_DENY.
      expires is the time after which the entry will be deleted
      automatically, and should be based off of
      CosmSystemClock time.
    


    
Return Values

    

      COSM_PASS on success, or COSM_FAIL on failure.
    


    
Errors

    

      COSM_PASS on success, or COSM_FAIL on failure.
    


    
Example






    


    
    

      CosmNetACLDelete
    


    
Syntax



#include "cosm/os_net.h"
s32 CosmNetACLDelete( cosm_NET_ACL * acl, cosm_NET_ADDR ip, u32 mask_bits );




    
Description

    

      Delete the ip/mask entry from the acl.
    


    
Return Values

    

      COSM_PASS on success, or COSM_FAIL on failure.
    


    
Errors

    

      COSM_PASS on success, or COSM_FAIL on failure.
    


    
Example






    


    
    

      CosmNetACLCheck
    


    
Syntax



#include "cosm/os_net.h"
s32 CosmNetACLCheck( cosm_NET_ACL * acl, cosm_NET_ADDR 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 COSM_NET_ALLOW
      setting at the end. The default is to allow (a NULL or empty acl).
    


    
Return Values

    

      COSM_NET_ALLOW if accepted, or COSM_NET_DENY if rejected.
    


    
Errors

    

      COSM_PASS on success, or COSM_FAIL on failure.
    


    
Example






    


    
    

      CosmNetACLFree
    


    
Syntax



#include "cosm/os_net.h"
void CosmNetACLFree( cosm_NET_ACL * acl );




    
Description

    

      Free the internal acl data.
    


    
Return Values

    

      None.
    


    
Errors

    

      None.
    


    
Example











  

    © Copyright Mithral Communications & Design Inc.
    
    1995-2025.
    All rights reserved.
    Mithral® and Cosm® are trademarks of
    Mithral Communications & Design Inc.
    

    
    Document last modified: Jun 01, 2012