Dale, Jonathan

English

Southampton (e-Prints Soton)

UNIVERSITY OF SOUTHAMPTONDEPARTMENT OF ELECTRONICS AND COMPUTER SCIENCETHE COMMUNICATION ROUTINES— A NETWORK LAYERCOMMUNICATION MODELJonathan DaleUniversity of SouthamptonTechnical Report No. 95-2January 1995ISBN: 0-854-325-7861The Communication Routines - A Network Layer Communication ModelJonathan DaleMultimedia Research GroupDepartment of Electronics and Computer ScienceUniversity of SouthamptonUKjd94r@ecs.soton.ac.uk1. IntroductionThe Communication Routines are a small set of C function calls that provide stream (reliable, connection-oriented) and datagram (best-try, connection-less) communication within the Transmission ControlProtocol/Internet Protocol (TCP/IP) communication stack. They are based around the Inter-ProcessCommunication (IPC) mechanism called sockets, which provide both stream and datagram orientedservices.The design criteria for the Communication Routines were based upon the following considerations:• To provide a suitable application interface to the sockets IPC which would allow a certain level ofabstraction between the networking layer (TCP/IP and sockets) and the application layer (client-server software).• To allow client-server software to be built rapidly and easily.• To be available across UNIX and Winsock compatible (PC) platforms.2. Network CommunicationIn the TCP/IP networking environment, communication generally takes place between clients andservers, hence the term client-server relationships. A server is a network entity which provides a set ofservices to a range of clients. Clients can connect to various servers to take advantage of services, whichthe servers undertake on their behalf. It follows, then, that some form of message exchange (that is,communication) must take place between the client and the server, and vice-versa.TCP/IP supports two essential modes of network communication:• Streams are a connection-oriented form of communication, which means that there is a persistentconnection between the client and the server for the duration of the communication (rather like atelephone conversation). Figure 1 illustrates that the client and the server are synchronised duringtheir communication.• Datagrams are a connection-less form of communication, which means that there is not a persistentconnection between the client and the server. Each message between the client and the server is aseparate connection, containing its own addressing information (this is analogous to the postal mailservice). With datagram client-server relationships, the client is not tied to the server for the durationof the request, nor is the server tied to the client after is has completed the work for that client; theyare both said to exist asynchronously. The essential difference between stream and datagramcommunication is that streams are persistent for the entire communication and require set-up,whereas datagrams are transient and do not require any set-up. This is shown in figure 2.A third communication exists, called broadcasting, which is a variation of the datagram communication.Broadcasting allows a client or a server send the same message to every network entity within the localnetwork (called the subnet). This can be useful for a number of reasons, for example, propagatingcommon data to an entire network, searching for a particular service within the network, etc. Eachnetwork entity receives the broadcasted message and either passes it onto an appropriate software2entity which it is running or discards it as unwanted. Broadcasting, however, should be kept to aminimum since it can flood the network and reduce performance.For datagram and broadcast communication channels, the maximum amount of data that can betransmitted at a time is 8192 bytes. For streams, any amount of data can be written to the communicationchannel but it is the responsibility of the receiving network entity to read the data in a sensible fashion.Figure 1 : Client-Server Communication Pattern in a Stream CommunicationCLIENT SERVERSend request and dataReceive requestProcess request and generate resultsSend resultsReceive resultsMore requests and results...TIME(possibly from other clients)Figure 2 : Client-Server Communication Pattern in a Datagram CommunicationCLIENT SERVEROpen connection requestRespond to connection requestReceive open connection requestReceive responseSend request and dataReceive requestProcess request and generate resultsSend resultsReceive resultsMore requests and results...Close connection requestReceive close requestTIME5platform that supports ANSI C and networking sockets.5. Function Reference5.1. API Summary1. int CR_RegisterServer (int nLocalPort, int nConnectionType)Registers a server-style communication channel.2. int CR_RegisterClient (LPSTR szRemoteIPAddress, int nRemotePort, int nConnectionType)Registers a client-style communication channel.3. int CR_Accept (int nReceivingHandle)Completes a client-server stream communication channel.4. INT CR_Send (int nHandle, LPHSTR lphszData, INT IBytesToSend, int nTimeout)Sends data to a communication channel.5. INT CR_Receive (int nHandle, LPHSTR lphszData, INT IBytesToRead)Reads data from a communication channel.6. INT CR_ReceiveN (int nHandle, LPHSTR lphszData, INT IBytesToRead, int nTimeout)Attempts to read data from a communication channel until all of the required amount of bytes havebeen read or the timeout has been reached.7. int CR_GetInfo (int nHandle, LPINT lpiPort, LPSTR lpszIPAddress, int nInfoType)Obtains information about the local or remote machine attached to a given communication channel.8. int CR_GetIPAddress (LPSTR lpszHostName, LPSTR lpszIPAddress)Obtains the Internet address for a given hostname.9. int CR_GetLastError (void)Returns the error code associated with the last communication routine error that occurred.10.int CR_Unaccept (int nSecondaryHandle)Disassociates the server from a client in a stream communication channel.11.int CR_Unregister (int nPrimaryHandle)Figure 3 : Network Abstraction through an Intermediate LayerNetwork Abstraction LayerApplication LayerEthernetEthernetNetwork LayerPhysical LayerDataStreamsPacketsCommunicationRoutinesProgrammingLanguageTCP/IPNetworkIndependentNetworkDependent6Unregisters a communication channel.12.int CR_UnregisterAll (void)Unregisters all registered communication channels.5.2. int CR_RegisterServer (int nLocalPort, int nConnectionType)PurposeRegisters a server-style connection for either stream or datagram communication. A server-styleconnection is characterised by the fact that the server typically ‘listens’ on the specified port, awaitingdata from a client.ParametersnLocalPortThe local port number to use for the connection. If this value is 0, then any local port is used (useCR_GetInfo to determine which port has been chosen).nConnectionTypeThe type of connection to make. It can be either STREAM for a duplex virtual circuit connection,DATAGRAM for a datagram connection, or BROADCAST for a datagram broadcasting connection.Return valuesThe primary handle onto the communication channel. If there was a communication problem, thenCOMM_ERROR is returned, else if there was a problem adding the registration details, thenLINK_ERROR is returned.Error codesCECANTBCASTA server cannot make a broadcast connection.LECANTADDHANDLEThe handle associated with this registration could not be created.See alsoCR_Send; CR_Receive; CR_GetInfo; CR_Unregister5.3. int CR_RegisterClient (LPSTR szRemoteIPAddress, int nRemotePort, int nConnectionType)PurposeRegisters a client-style connection for either stream or datagram communication. A client-styleconnection is characterised by the fact that the client typically writes data through a port to a waitingserver, hence the need to specify a remote Internet address and port number.ParametersszRemoteIPAddressThe remote Internet address of the server.nRemotePortThe remote port number of the server.nConnectionTypeThe type of connection to make. It can be either STREAM for a duplex virtual circuit connection,DATAGRAM for a datagram connection, or BROADCAST for a datagram broadcasting connection.Return valuesThe primary handle onto the communication channel. If there was a communication problem, thenCOMM_ERROR is returned, else if there was a problem adding the registration details, thenLINK_ERROR is returned.Error codesCECANTCONNECTThe client could not connect correctly with the specified server.LECANTADDHANDLEThe handle asscoaited with this registration could not be created.LECANTALLOCMEM7Memory allocation failed.LECANTADDINFOThe registration information associated with this communication channel could not be added.NotesCR_RegisterClient allocates any local port number (use CR_GetInfo to determine which port has beenchosen).See alsoCR_Send; CR_Receive; CR_GetInfo; CR_Unregister5.4. int CR_Accept (int nReceivingHandle)PurposeAccepts a stream-style connection from a client. This function should be issued by the server in responseto a CR_RegisterClient function that has been issued by the client. A communication channel must havebeen established on both the server and the client beforehand.ParameternReceivingHandleThe handle onto the communication channel.Return valuesA secondary handle if the communication was accepted successfully. If there was a communicationproblem, then COMM_ERROR is returned, else if a communication channel has not been previouslyregistered, then LINK_ERROR is returned.Error codesCESTREAMONLYThis function can only be used with stream communication channels.CECANTACCEPTThe server could not accept correctly with a client.LECANTADDHANDLEThe secondary handle to be associated with this communication channel could not be created.LECANTGETHANDLEThe primary handle associated with this communication channel could not be located.LECANTADDINFOThe registration information associated with this communication channel could not be added.NotesThis function should only be used on stream-style connections. A server can only accept on oneconnection at a time for each primary handle.See alsoCR_Unaccept5.5. INT CR_Send (int nHandle, LPHSTR lphszData, INT IBytesToSend, int nTimeout)PurposeSends data to a communication channel.ParametersnHandleThe handle onto the communication channel.lphszDataThe data to send to the communication channel.IBytesToSendThe amount of data to send to the communication channel.nTimeoutThe amount of time (in seconds) before the connection will timeout.8Return valuesThe number of bytes sent if the data was written successfully. If there was a communication problem,then COMM_ERROR is returned, else if the communication channel has not been previously registered,then LINK_ERROR is returned.Error codesCECANTWRITEDATAThe data could not be send to the communication channel.CECANTREADDATAThe protocol between the client and the server could not be established.CETIMEOUTThe timeout period has expired.CEDATATOOBIGThe data to be sent is too large for the communication channel (for datagram and broadcastcommunication channels only).LECANTALLOCMEMMemory allocation failed.LECANTGETHANDLEThe primary or secondary handle associated with this communication channel could not be located.NotesA timeout is not considered to be an error, even though CR_GetLastError will return CETIMEOUT.See alsoCR_Receive; CR_ReceiveN5.6. INT CR_Receive (int nHandle, LPHSTR lphszData, INT IBytesToRead)PurposeReads data from a communication channel.ParametersnHandleThe handle onto the communication channel.lphszDataThe resultant data that has been read from the communication channel.IBytesToReadThe amount of data to read from the communication channel.Return valuesThe number of bytes read if the data was read successfully. If there was a communication problem, thenCOMM_ERROR is returned, else if the communication channel has not been previously registered, thenLINK_ERROR is returned.Error codesCECANTREADDATAThe data could not be read from the communication channel.CECANTWRITEDATAThe protocol between the client and the server could not be established.LECANTALLOCMEMMemory allocation failed.LECANTGETHANDLEThe primary or secondary handle associated with this communication channel could not be located.LECANTADDINFOThe registration information associated with this communication channel could not be added orupdated.NotesIf there is no data waiting at the communication channel, then this function will block until it arrives.However, it will not block until all of the requested data arrives (see CR_ReceiveN for a fully blocking9receive function). Additionally, this function can only send stream data of a maximum size of 32767bytes (use CR_ReceiveN to send data that is over this limit).See alsoCR_Send; CR_ReceiveN5.7. INT CR_ReceiveN (int nHandle, LPHSTR lphszData, INT IBytesToRead, int nTimeout)PurposeAttempts to read data from a communication channel until all of the required amount of bytes have beenread or the timeout has been reached.ParametersnHandleThe handle onto the communication channel.lphszDataThe resultant data that has been read from the communication channel.IBytesToReadThe amount of data to read from the communication channel.nTimeoutThe amount of time (in seconds) before the connection will timeout.Return valuesThe number of bytes read if the data was read successfully. If there was a communication problem, thenCOMM_ERROR is returned, else if the communication channel has not been previously registered, thenLINK_ERROR is returned.Error codesCECANTREADDATAThe data could not be read from the communication channel.CECANTWRITEDATAThe protocol between the client and the server could not be established.CETIMEOUTThe timeout period has expired.LECANTALLOCMEMMemory allocation failed.LECANTGETHANDLEThe primary or secondary handle associated with this communication channel could not be located.LECANTADDINFOThe registration information associated with this communication channel could not be added orupdated.NotesIf there is no data waiting at the communication channel, then this function will block until it arrives. Atimeout is not considered to be an error, even though CR_GetLastError will return CETIMEOUT.See alsoCR_Send; CR_Receive5.8. int CR_GetInfo (int nHandle, LPINT lpiPort, LPSTR lpszIPAddress, int nInfoType)PurposeInterrogates either the local or remote address structure of a registered communication channel,yielding the port number and Internet address.ParametersnHandleThe handle onto the communication channel.lpiPort10The resultant port number of the remote machine.lpszIPAddressThe resultant Internet address of the remote machine.nInfoTypeThe type of information to return. If this is CR_LOCAL, then the details of the local host are returned,else if this is CR_REMOTE, then the details of the currently connected remote host are returned.Return valuesTRUE if the remote address structure was interrogated successfully. If there was a problem retreivingthe local or remote machine information, then COMM_ERROR is returned, else if there is no completeremote address structure associated with the communication channel, then LINK_ERROR is returned.Error codesLECANTQUERYHNDLThe communication channel could not be interrogated to determine additional registration information.LECANTGETINFOThe registration information associated with this communication channel could not be located.NotesThe remote address structure for a stream-style connection is completed when a CR_Accept function hasbeen issued (and the connection is made). For a datagram-style connection, the remote address structureis updated each time a CR_Receive is issued (since many different clients can connect to one server). Thismeans that until the first client sends data, the remote address structure for a datagram-style connectionwill be incomplete.5.9. int CR_GetIPAddress (LPSTR lpszHostName, LPSTR lpszIPAddress)PurposeLooks up the Internet address of a machine within the local name server or local hosts file.ParameterslpszHostNameThe host name of the machine to look-up.lpszIPAddressThe resultant Internet address of the specified machineReturn valuesTRUE if the Internet address of the machine was looked-up successfully. If there was a problemobtaining the Internet address, then LINK_ERROR is returned.Error codeLECANTQUERYHOSTThe local host could not be queried for relevant information.5.10. int CR_GetLastError (void)PurposeReturns an error code that is associated with the last error that occurred.Return valueCEOKAY if no error occurred, else the error code associated with the last error.NotesTwo types of errors can be returned by the Communication Routine functions; communication errors(COMM_ERROR) and link errors (LINK_ERROR). A communication error indicates that thecommunication subsystem has failed and a link error means that there was a problem setting up thelocal registration information within the link handler. Error codes preceded with CE detail acommunication error and error codes preceded with LE represent a link error.115.11. int CR_Unaccept (int nSecondaryHandle)PurposeDisconnects the server from a stream-style connection with the client. The server is now free to acceptanother stream-style connection from another client or to unregister its primary handle.ParameternSecondaryHandleThe secondary handle to disconnect.Return valuesTRUE if the secondary handle was disconnected successfully. If there was a communication problem,then COMM_ERROR is returned, else if the secondary handle does not exist, then LINK_ERROR isreturned.Error codesCESTREAMONLYThis function can only be used with stream communication channels.CECANTCLOSEHNDLThe communication channel could not be unregistered or closed.LECANTGETHANDLEThe secondary handle associated with this communication channel could not be located.LECANTDELHANDLEThe secondary handle associated with this communication channel could not be removed.NotesA secondary handle should be unaccepted before its corresponding primary handle is unregistered.See alsoCR_Accept; CR_Unregister5.12. int CR_Unregister (int nPrimaryHandle)PurposeUnregisters a communication channel and closes the connection with the attached remote machine.ParameternPrimaryHandleThe primary handle to disconnect.Return valuesTRUE if the primary handle was disconnected successfully. If there was a communication problem, thenCOMM_ERROR is returned, else if the primary handle does not exist, then LINK_ERROR is returned.Error codesCECANTCLOSEHNDLThe communication channel could not be unregistered or closed.LECANTGETHANDLEThe primary handle associated with this communication channel could not be located.LECANTDELHANDLEThe primary handle associated with this communication channel could not be removed.NotesA secondary handle should be unaccepted before its corresponding primary handle is unregistered.See alsoCR_Unaccept5.13. int CR_UnregisterAll (void)PurposeUnregisters all communication channels and closes the connections with all attached remote machines.Return values12TRUE if all of the connections were unregistered and closed successfully. If any remote machine couldnot be unregistered, then LINK_ERROR is returned.Error codesLECANTDELHANDLEA primary or secondary handle could not be removed.NotesAll secondary handles should be unaccepted before this function is called. CR_Unregister should be usedto unregister individual connections.See alsoCR_Unaccept; CR_Unregister

The Communication Routines - A Network Layer Communication Model

Abstract

Similar works

Full text

Available Versions

Southampton (e-Prints Soton)