[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-2017. All rights reserved. Mithral® and Cosm® are trademarks of Mithral Communications & Design Inc.
Document last modified: Jun 01, 2012