Up

NetTCP reference

Authors

Andrew Ruder (aeruder@ksu.edu)

Version: Revision 1

Date: November 8, 2003

Copyright: (C) Andrew Ruder


Contents -

  1. Software documentation for the TCPConnecting class
  2. Software documentation for the TCPPort class
  3. Software documentation for the TCPSystem class
  4. Software documentation for the TCPTransport class
  5. Software documentation for the TCPConnecting protocol
  6. NetTCP variables

Software documentation for the TCPConnecting class

TCPConnecting : NSObject

Declared in:
NetTCP.h
Conforms to:
NetObject

If an object was attempted to have been connected in the background, this is a placeholder for that ongoing connection. -connectNetObjectInBackground:toHost:onPort:withTimeout: will return an instance of this object. This placeholder object can be used to cancel an ongoing connection with the -abortConnection method.



Instance Variables for TCPConnecting Class

netObject

@private id netObject;

Description forthcoming.


timeout

@private NSTimer* timeout;

Description forthcoming.


transport

@private id transport;

Description forthcoming.





Method summary

abortConnection 

- (void) abortConnection;

Aborts the ongoing connection. If the net object conforms to the <TCPConnecting> protocol, it will receive a [<TCPConnecting>-connectingFailed:] message with a argument of NetclassesErrorAborted


connectionEstablished: 

- (id) connectionEstablished: (id<NetTransport>)aTransport;

Sets up the connection placeolder. If the net object conforms to <TCPConnecting> , it will receive a [<TCPConnecting>-connectingStarted:] with the instance of TCPConnecting as an argument.


connectionLost 

- (void) connectionLost;

Cleans up the connection placeholder.


dataReceived: 

- (id) dataReceived: (NSData*)data;

This shouldn't happen while a class is connecting, but included to conform to the <NetObject> protocol.


netObject 

- (id<NetObject>) netObject;

Returns the object that will be connected by this placeholder object.


transport 

- (id<NetTransport>) transport;

Returns the transport used by this object. Will not be the same transport given to the net object when the connection is made.


Software documentation for the TCPPort class

TCPPort : NSObject

Declared in:
NetTCP.h
Conforms to:
NetPort

TCPPort is a class that is used to bind a descriptor to a certain TCP/IP port and listen for connections. When a connection is received, it will create a class set with -setNetObject: and set it up with the new connection.



Instance Variables for TCPPort Class

desc

@private int desc;

Description forthcoming.


netObjectClass

@private Class netObjectClass;

Description forthcoming.


port

@private uint16_t port;

Description forthcoming.





Method summary

close 

- (void) close;

Closes the descriptor.


connectionLost 

- (void) connectionLost;

Called when the connection is closed. This will call -close


desc 

- (int) desc;

Returns the low-level file descriptor for the port.


initOnHost: onPort: 

- (id) initOnHost: (NSHost*)aHost onPort: (uint16_t)aPort;

Initializes a port on aHost and binds it to port aPort. If aHost is nil, it will set it up on all addresses on the local machine. Using zero for aPort will use a random currently available port number. Use -port to find out where it is actually bound to.


initOnPort: 

- (id) initOnPort: (uint16_t)aPort;

Calls -initOnHost:onPort: with a nil argument for the host.


newConnection 

- (id) newConnection;

Called when a new connection occurs. Will initialize a new object of the class set with -setNetObject: with the new connection.


port 

- (uint16_t) port;

Returns the port that this TCPPort is currently bound to.


setNetObject: 

- (id) setNetObject: (Class)aClass;

Sets the class that will be initialized if a connection occurs on this port. If aClass does not implement the <NetObject> protocol, will throw a FatalNetException.


Software documentation for the TCPSystem class

TCPSystem : NSObject

Declared in:
NetTCP.h

Used for certain operations in the TCP/IP system. There is only one instance of this class at a time, used +sharedInstance to get this instance.



Instance Variables for TCPSystem Class

errorNumber

@private int errorNumber;

Description forthcoming.


errorString

@private NSString* errorString;

Description forthcoming.





Method summary

sharedInstance 

+ (id) sharedInstance;

Returns the one instance of TCPSystem currently in existence.


connectNetObject: toHost: onPort: withTimeout: 

- (id<NetObject>) connectNetObject: (id<NetObject>)netObject toHost: (NSHost*)aHost onPort: (uint16_t)aPort withTimeout: (int)aTimeout;

Will connect the object netObject to host aHost on port aPort. If this connection doesn't happen in aTimeout seconds or some other error occurs, it will return nil and the error string and error number shall be set accordingly. Otherwise this will return netObject


connectNetObjectInBackground: toHost: onPort: withTimeout: 

- (TCPConnecting*) connectNetObjectInBackground: (id<NetObject>)netObject toHost: (NSHost*)aHost onPort: (uint16_t)aPort withTimeout: (int)aTimeout;

Connects netObject to host aHost on the port aPort. Returns a place holder object that finishes the connection in the background. The placeholder will fail if the connection does not occur in aTimeout seconds. Returns nil if an error occurs and sets the error string and error number accordingly.


errorNumber 

- (int) errorNumber;

Returns the errno of the last error that occurred. If it is some other non-system error, this will be zero, but the error string shall be set accordingly.


errorString 

- (NSString*) errorString;

Returns the error string of the last error that occurred.


hostFromHostOrderInteger: 

- (NSHost*) hostFromHostOrderInteger: (uint32_t)ip;

Returns a host from a host order 32-bit integer ip address.


hostFromNetworkOrderInteger: 

- (NSHost*) hostFromNetworkOrderInteger: (uint32_t)ip;

Returns a host from a network order 32-bit integer ip address.


Software documentation for the TCPTransport class

TCPTransport : NSObject

Declared in:
NetTCP.h
Conforms to:
NetTransport

Handles the actual TCP/IP transfer of data.



Instance Variables for TCPTransport Class

connected

@private BOOL connected;

Description forthcoming.


desc

@private int desc;

Description forthcoming.


localHost

@private NSHost* localHost;

Description forthcoming.


remoteHost

@private NSHost* remoteHost;

Description forthcoming.


writeBuffer

@private NSMutableData* writeBuffer;

Description forthcoming.





Method summary

close 

- (void) close;

Closes the transport nd makes sure there is no more incoming or outgoing data on the connection.


desc 

- (int) desc;

Returns the low level file descriptor that is used internally.


initWithDesc: withRemoteHost: 

- (id) initWithDesc: (int)aDesc withRemoteHost: (NSHost*)theAddress;

Initializes the transport with the file descriptor aDesc. theAddress is the host that the flie descriptor is connected to.


isDoneWriting 

- (BOOL) isDoneWriting;

Returns YES if there is no more data to write in the buffer and NO if there is.


localHost 

- (NSHost*) localHost;

Returns a NSHost of the local side of a connection.


readData: 

- (NSData*) readData: (int)maxDataSize;

Handles the actual reading of data from the connection. Throws an exception if an error occurs while reading data.


remoteHost 

- (NSHost*) remoteHost;

Returns a NSHost of the remote side of a connection.


writeData: 

- (id) writeData: (NSData*)aData;

If aData is nil, this will physically transport the data to the connected end. Otherwise this will put the data in the buffer of data that needs to be written to the connection when next possible.


Software documentation for the TCPConnecting protocol

TCPConnecting

Declared in:
NetTCP.h

A class can implement this protocol, and when it is connected in the background using -connectNetObjectInBackground:toHost:onPort:withTimeout: it will receive the messages in this protocol which notify the object of certain events while being connected in the background.

Method summary

connectingFailed: 

- (id) connectingFailed: (NSString*)aError;

Tells the class implementing this protocol that the error in aError has occurred and the connection will not be established


connectingStarted: 

- (id) connectingStarted: (TCPConnecting*)aConnection;

Tells the class implementing this protocol that the connection has begun and will be using the connection place holder aConnection


NetTCP variables

NetclassesErrorAborted

NSString* NetclassesErrorAborted;

The error message used when a connection is aborted.


NetclassesErrorBadAddress

NSString* NetclassesErrorBadAddress;

Could be the current error string if the error number is zero and some error has occurred. Indicates that a NSHost returned an address that was invalid.


NetclassesErrorTimeout

NSString* NetclassesErrorTimeout;

If an error occurs and error number is zero, this could be the error string. This error occurs when some operation times out.



Up