home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / e / extralib / !ExtrasLib / h / Socket < prev    next >
Text File  |  1996-03-03  |  3KB  |  96 lines
  1. /* Socket.h */
  2.  
  3. /* ExtrasLib by Peter Hartley 1995-96
  4.  * (K) All Rites Reversed - Copy What You Like
  5.  */
  6.  
  7. typedef struct Socket *Socket;      /* abstract type */
  8.  
  9. typedef enum {
  10.     socket_STREAM = 1,              /* not implemented in InternetA */
  11.     socket_DATAGRAM,
  12.     socket_RAW
  13. } socket_type;
  14.  
  15. typedef struct {
  16.     unsigned short  family;
  17.     unsigned short  port;
  18.     unsigned int    address;
  19.     char            _zero[8];
  20. } socket_description;
  21.  
  22. #define address_BROADCAST 0xFFFFFFFF
  23.  
  24. os_error *Socket_Create( Socket *s, socket_type type );
  25. os_error *Socket_SendTo( Socket s, void *message, int messagelen,
  26.                          unsigned int ipaddress, int port );
  27. int       Socket_RecvFrom( Socket s, void *buffer, int buflen,
  28.                            unsigned int *wasfrom );
  29.  
  30. /* these options are off by default, which with NonBlocking is very
  31.    unlikely to be what you want */
  32. os_error *Socket_NonBlocking( Socket s, BOOL nonblocking );
  33. os_error *Socket_Asynchronous( Socket s, BOOL asynchronous );
  34. os_error *Socket_AllowBroadcast( Socket s, BOOL allowed );
  35.  
  36. os_error *Socket_Describe( Socket s, socket_description *desc );
  37. os_error *Socket_Bind( Socket s, int port );
  38. os_error *Socket_Close( Socket *s );
  39.  
  40. /*  Typical code which reads from a socket:
  41.  
  42.         Socket s;
  43.         unsigned int sender;
  44.  
  45.         Socket_Create( &s );
  46.         Socket_Bind( s, <port number> );
  47.         Socket_NonBlocking( s, TRUE );  |* RecvFrom stiffs otherwise *|
  48.         etc
  49.         for (;;)
  50.         {
  51.             Wimp_Poll()
  52.             etc
  53.             if ( Socket_RecvFrom( s, buffer, sizeof(buffer), &sender ) )
  54.             {
  55.                 process information in buffer
  56.                 ('sender' has been filled in with the sender's address)
  57.             }
  58.         }
  59.         Socket_Close( s );
  60.  
  61.     Writing to a socket:
  62.  
  63.         Socket_Create( &s );
  64.         |* Socket_AllowBroadcast( s, TRUE ); *|  (optionally)
  65.         etc
  66.         Socket_Sendto( s, buffer, sizeof(buffer), <address>, <port number> );
  67.         etc
  68.         Socket_Close( s );
  69.  
  70.     The same socket can be used for reading and writing.
  71.     If your program terminates without calling Socket_Close, the
  72. socket remains open, and any further attempts to connect to the same
  73. port number will fail. Moral: *don't* call Socket_Close at the end of
  74. your program, as in the fragments above! - put it in an atexit()
  75. handler instead.
  76.  
  77.     An asynchronous socket is one which generates Internet events when
  78. packets arrive. Note that the PRM is WRONG - your event handler is called
  79. with event_INTERNET = 19 in R0 sure enough, and the socket number in
  80. R2, but R1 contains internetevent_URGENT = 1.
  81.  
  82.     To read your own internet address, read the system variable
  83. Inet$LocalAddr, which is a string containing the address as 8 hex digits.
  84.  
  85.     Port numbers must be supplied with the bytes the wrong way round -
  86. eg, to connect to 'talk' (port number 0x205) set sd.port = 0x502.
  87.     Internet addresses must also be supplied with the bytes the wrong
  88. way round - i.e. station number in most significant byte etc. - but
  89. this is the way round Inet$LocalAddr has it anyway.
  90.  
  91.     Rather than use your own broadcast messages and dedicated port, a
  92. good way to announce the availability of a service is to obtain any
  93. unallocated port, and then use Freeway to distribute the port number
  94. and your internet address to anyone who might be interested.
  95.     */
  96.