UDP.library/Close_UDP
UDP.library/Comms_Housekeeping
UDP.library/Connect_to_Server
UDP.library/Disconnect_From_Game
UDP.library/Get_Comms_Data
UDP.library/Get_Comms_System_Information
UDP.library/Get_Comms_Variable
UDP.library/Get_Host_By_Name
UDP.library/Initialise_Server
UDP.library/Localhost_Name
UDP.library/Send_Easy_Message
UDP.library/Send_Reliable_Message
UDP.library/Send_Unreliable_Message
UDP.library/Set_Comms_System_Information
UDP.library/Set_Comms_Variable
NAME
Close_UDP - Close UDP socket and buffers.
SYNOPSIS
Close_UDP()
VOID Close_UDP(VOID);
FUNCTION
This closes the UDP socket of our program and frees up any
resources used.
NOTES
This command closes the UDP socket, closes the bsdsocket library,
and closes all buffers associated with the UDP conection.
SEE ALSO
Initialise_Server()
BUGS
NAME
Comms_Housekeeping - Does various UDP housekeeping tasks every
frame.
SYNOPSIS
Comms_Housekeeping()
VOID Comms_Housekeeping(VOID);
FUNCTION
This does various Comms housekeeping tasks, like check wether any
packets need resending because of timeouts, or wether any requested
disconnections (to Server or Client), have timed out. Also it checks wether
any Time Syncs need sending.
NOTES
This Function should be called once per frame in your Main loop.
SEE ALSO
BUGS
NAME
Connect_to_Server - Allows a Client to attempt to connect to a
mUDPie Server.
SYNOPSIS
result = Connect_to_Server(host,port,localhost_name,localport)
UWORD Connect_to_Server(STRPTR,UWORD,STRPTR,UWORD) ;
FUNCTION
Attempt to connect to a mUDPie Server at hostname and port. Also
your local hostname and port to bind to must be specified as well- this allows
you to bind to your Internet or LAN hostname. It first initialises a UDP
socket on your localhost, and then binds a port number to it, so it can
receive incoming data packets on that port. It then allocates some data
buffers, and attempts to connect to Server.
INPUTS
host - Server hostname to connect to- this is a pointer to a string, either
a string name or Dot name (like 107.myserver.com, 192.168.0.1 or localhost (to run multiple
programs on one machine)).
port - Port number on Server to connect to- from 0-65535. Currently
it is a UWORD, but this will change to ULONG soon.
localhost_name - This is a pointer to a string with either a Dot address (A.B.C.D),
or a string name (www.google.com). This can be either the host machine's (that the program is
running on) Internet address, LAN address (for LAN games), or localhost name (for running
multiple copies of your program on the same machine).
localport - local port number to bind to- from 0-65535. You should
only specify a number from 1024 onwards- all numbers lower than that are
reserved. Currently it is a UWORD, but this will change to ULONG soon.
RESULTS
result - either TRUE(-1), FALSE (0), or PORT_BIND_FAILED
(constant). If True then a UDP socket was set up, had the port number bound
to it, had buffers allocated, and attempted to connect to the Server. If False
then either the Client is already online, a socket couldn't be initialised,
or buffers couldn't be allocated. If PORT_BIND_FAILED, then the socket
couldn't be bound to that port number.
NOTES
It doesn't block and wait for a reply, it just initiates the
connection- see CONNECTION_ACCEPTED or CONNECTION_REQUEST_REJECTED in
Process_Comms_Information() in UDP_Chat for reply from Server.
It attempts to open the bsdsocket.library, initialise memory buffers, open a UDP
socket and bind the given port number to the socket. You do not need a IP stack (TCP/IP stack)
to be running when you start your program, as it is only opened when you call Connect_To_Server()
or Initialise_Server(). This way, if you are only running a single-player game you do not need
an IP stack running first, or to allocate the extra memory.
You can use Localhost_Name()
to find your Internet host name for localhost_name.
See `Try to connect to a Server' in Window_Events(), in UDP_Chat
for an example of auto-trying higher port numbers, for testing multiple
programs on localhost.
SEE ALSO
Close_UDP() ,
Disconnect_From_Game() ,
Initialise_Server() ,
Localhost_Name()
BUGS
NAME
Disconnect_From_Game - This shuts down network (game) if we're
the Server, or disconnects us from the network (game) if we're a Client.
SYNOPSIS
Disconnect_From_Game()
VOID Disconnect_From_Game(VOID);
FUNCTION
If we're the Server it tells all the Clients that the network
session (game) is over, and if we're a Client we tell the Server we're
leaving the network (game).
NOTES
This doesn't disconnect the network (game), or disconnect the
Client immediately. If we're the Server we tell all the Clients that the
network session (game) is over, and then waits to get a confirmation from
all Clients- see WE_ARE_OFFLINE in Process_Comms_Information() in UDP_Chat
for confirmation that all Clients have disconnected. If we're a Client we
tell the Server we're disconnecting, and then wait for confirmation from
the Server that we're disconnected- see WE_ARE_DISCONNECTED_FROM_THE_GAME
in Process_Comms_Information() in UDP_Chat for confirmation that we have
disconnected from network (game).
SEE ALSO
Close_UDP()
BUGS
NAME
Get_Comms_Data - this call gives back any user comms (game) data,
that may be waiting, in a buffer.
SYNOPSIS
memoryBlock = Get_Comms_Data()
VOID *Get_Comms_Data(VOID);
FUNCTION
This Function passes back a buffer with the data received from the
Server or Clients, and other relevant information on the data like size of
data, protocol type and player number.
RESULTS
memoryBlock - Pointer to a buffer that holds header info and data,
or FALSE (0), if no data was waiting.
Header:
ULONG- size of data (ignoring size of header)
UWORD- protocol type
UWORD- player number data received from
Then data follows (memoryBlock +8 bytes).
NOTES
This does the main work of getting data sent to your program- if
the program is the Server then this data will have to be sent on to the other
Clients, or they will not receive it. This allows you to filter/check/change
any information coming in before sending it out again to the Clients.
SEE ALSO
BUGS
It should return a Structure, consisting of the header and a
pointer to the beginning of data. It soon will also give back the packet
number in the header too.
UDP.lib/Get_Comms_System_Information
NAME
Get_Comms_System_Information - get any comms system messages to
respond to and/or print out.
SYNOPSIS
memoryBlock = Get_Comms_System_Information()
VOID *Get_Comms_System_Information(VOID);
FUNCTION
Any comms system messages are put into a buffer by
Set_Comms_System_Information()
- this function retrieves them, and any extra data appropriate to the
message.
RESULTS
memoryBlock - this gives back a pointer to the place in the buffer
where the ULONG code for the message is stored, or FALSE (0) if no messages
are waiting.
Up to 5 pieces of data (ULONGs), can also be accessed which can
add extra information for the message code. The number of extra pieces of
information is dependant on the message code.
Message codes are referenced as constants (see
Process_Comms_Information() in UDP_Chat for an example).
Example buffer location pointed to by memoryBlock:
| Size | Value | Description |
| ULONG | NEW_PLAYER_ONLINE | - Message code |
| ULONG | 2 | - Player number |
| ULONG | 6789201 | - Host address (in ULONG format) |
| ULONG | 27272- Port number |
NOTES
This Function should be called in a loop until a FALSE is returned,
once per frame, otherwise the buffer could get overflowed (and comms system
messages will be lost)- the
COMMS_SYSTEM_INFORMATION_ARRAY_OVERFLOW error in
Process_Comms_Information() in UDP_Chat will be printed if that happens.
The constants given back are listed in the UDPHeader.
For an example of calling it see:
General_Housekeeping()
in UDP_Chat, and for dealing with the information (constants) given back see :
Process_Comms_Information()"
in UDP_Chat.
SEE ALSO
Set_Comms_System_Information() , General_Housekeeping() in UDP_Chat, Process_Comms_Information() in UDP_Chat
BUGS
NAME
Get_Comms_Variable - Get an internal library setting.
SYNOPSIS
result = Get_Comms_Variable(variable_code, variable_value)
ULONG Get_Comms_Variable(UWORD,ULONG)
FUNCTION
Used to get internal system parameters, like maximum number
of players, length of timeouts etc.
INPUTS
variable_code -
ONLINE_STATUS - returns either OFFLINE, CLIENT, SERVER OR
ATTEMPTING_TO_CONNECT- depending on wether the program is Offline, acting
as a Client, Server or is attemping to connect to a Server.
PLAYER_STATUS - and Client number in variable_value,
returns as in ONLINE_STATUS above. A Client number of 0 will act as in
ONLINE_STATUS (ie: this program's status).
RESULTS
As above, depending on variable_code.
NOTES
SEE ALSO
BUGS
NAME
Initialise_Server - Initialise this program as Server.
SYNOPSIS
result = Initialise_Server(localhost_name,localport,max_number_of_clients)
WORD Initialise_Server(STRPTR,UWORD,UWORD)
FUNCTION
This function initialises your program as a Server, and allows it to accept/deny
connections from client programs.
INPUTS
localhost_name - This is a pointer to a string with either a Dot address (A.B.C.D),
or a string name (www.google.com). This can be either the host machine's (that the program is
running on) Internet address, LAN address (for LAN games), or localhost name (for running
multiple copies of your program on the same machine).
localport - local port number to bind to- from 0-65535. You should
only specify a number from 1024 onwards- all numbers lower than that are
reserved. Currently it is a UWORD, but this will change to ULONG soon.
max_number_of_clients - This is the maximum number of clients/players that can
connect to the Server (this includes the Server as part of the number- ie: the Server is a
client too). Once this number of clients have connected, any more connection attempts will
be rejected, until a client disconnects or is disconnected.
RESULTS
result- True (-1), if server is correctly initialised, False (0), if it cannot be
initialised, or the constant PORT_BIND_FAILED, if the `localport' passed to the function is in
use (you should try a higher port number).
NOTES
It attempts to open the bsdsocket.library, initialise memory buffers, open a UDP
socket and bind the given port number to the socket. You do not need a IP stack (TCP/IP stack)
to be running when you start your program, as it is only opened when you call Connect_To_Server()
or Initialise_Server(). This way, if you are only running a single-player game you do not need
an IP stack running first, or to allocate the extra memory.
You can use Localhost_Name()
to find your Internet host name for localhost_name.
See `Server Button' in Window_Events(), in UDP_Chat
for an example of auto-trying higher port numbers, for testing multiple
programs on localhost.
SEE ALSO
Close_UDP() ,
Connect_to_Server(),
Disconnect_From_Game() ,
Localhost_Name()
BUGS
NAME
SYNOPSIS
;
FUNCTION
INPUTS
RESULTS
NOTES
SEE ALSO
BUGS
NAME
SYNOPSIS
;
FUNCTION
INPUTS
RESULTS
NOTES
SEE ALSO
BUGS
UDP.lib/Send_Unreliable_Message
NAME
SYNOPSIS
;
FUNCTION
INPUTS
RESULTS
NOTES
SEE ALSO
BUGS
UDP.lib/Set_Comms_System_Information
NAME
Set_Comms_System_Information - With this function you can add in your own
custom system information codes and data to go with them.
SYNOPSIS
Set_Comms_System_Information(message_code,data1,data2,data3,data4,data5)
VOID Set_Comms_System_Information(ULONG,ULONG,ULONG,ULONG,ULONG,ULONG)
FUNCTION
This function allows you to add in your own custom messages that
go though the UDP library system- so you can use the same routine to handle
your custom and UDP library system messages, instead of having to make an
extra routine for your custom messages.
INPUTS
message_code - your custom message code- this should be over
9,999 (all numbers less than 10,000 are reserved for system use!).
data1-data5 - these are ULONGs with which you can add extra
information to your message.
NOTES
See Process_Comms_Information()
in UDP_Chat, for examples of using the message system.
SEE ALSO
Get_Comms_System_Information ,
Process_Comms_Information() in UDP_Chat.
BUGS
NAME
Set_Comms_Variable - Change an internal library setting.
SYNOPSIS
result = Set_Comms_Variable(variable_code,variable_value)
UWORD Set_Comms_Variable(UWORD,ULONG)
FUNCTION
Used to adjust internal system parameters, like maximum number
of players, length of timeouts etc.
INPUTS
variable_code -
MAX_NUMBER_PLAYERS - change the maximum amount of clients that
can connect. variable_value can be from 0 to 65535 (UWORD)- 0 will set
all memory used to a minimal size.
This only works if client is offline (ie: neither a Client or
Server), otherwise a fail will be given back. Also a fail will be given back
if there's not enough system memory to allocate buffers for the amount of
Clients requested.
SYSTEM_TIME - this is the internal time that is synched for Server and
all Clients (optional system). Only a program acting as Server can resync
the time. variable_value is a ULONG. Returns True.
More variables to come! :)
RESULTS
True or False, depending on variable_code and system conditions.
NOTES
Don't play with variable codes you don't understand- you can
really screw up system performance, if you're not careful!
SEE ALSO
Get_Comms_Variable
BUGS