Up

NetBase reference

Authors

Andrew Ruder (aeruder@ksu.edu)

Version: Revision 1

Date: November 8, 2003

Copyright: (C) Andrew Ruder


Contents -

  1. Software documentation for the NetApplication class
  2. Software documentation for the NetObject protocol
  3. Software documentation for the NetPort protocol
  4. Software documentation for the NetTransport protocol
  5. Software documentation for the RunLoopEvents protocol
  6. NetBase types
  7. NetBase variables

Software documentation for the NetApplication class

NetApplication : NSObject

Declared in:
NetBase.h
Conforms to:
RunLoopEvents

NetApplication is the workhorse of netclasses. It manages all the connections and ports by inserting them into the runloop and calling the callback methods when appropriate. NetApplication is a singleton class; i.e. only one is in existence at a time. For this reason, always use +sharedInstance to get the appropriate instance.



Instance Variables for NetApplication Class

badDescs

@private NSMutableArray* badDescs;

Description forthcoming.


descTable

@private NSMapTable* descTable;

Description forthcoming.


netObjectArray

@private NSMutableArray* netObjectArray;

Description forthcoming.


portArray

@private NSMutableArray* portArray;

Description forthcoming.





Method summary

sharedInstance 

+ (id) sharedInstance;

Returns the instance of NetApplication for the current application.


closeEverything 

- (id) closeEverything;

Calls -disconnectObject: on every object currently in the runloop.


connectObject: 

- (id) connectObject: (id)anObject;

Inserts anObject into the runloop (and retains it). anObject should implement either the <NetPort> or <NetObject> protocols. Throws a NetException if the class follows neither protocol. After connecting anObject, it will begin to receive the methods designated by its respective protocol. anObject should only be connected with this after its transport is set.


disconnectObject: 

- (id) disconnectObject: (id)anObject;

Removes anObject from the runloop and releases it. anObject will no longer receive messages outlined by its protocol. Does not close the descriptor of anObject. anObject will receive a [<NetObject>-connectionLost] message or a [<NetPort>-connectionLost] message.

If any object should lose its connection, this will automatically be called with that object as its argument.


receivedEvent: type: extra: forMode: 

- (void) receivedEvent: (void*)data type: (RunLoopEventType)type extra: (void*)extra forMode: (NSString*)mode;

Should not be called. Used internally by NetApplication to receive events from the runloop.


timedOutEvent: type: forMode: 

- (NSDate*) timedOutEvent: (void*)data type: (RunLoopEventType)type forMode: (NSString*)mode;

Should not be called. Used internally by NetApplication to receive timed out events notifications from the runloop.


transportNeedsToWrite: 

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

This is called to notify NetApplication that aTransport has data that needs to be written out. Only after this method is called will aTransport begin to receive [<NetTransport>-writeData:] messages with a nil argument when it can write.


Software documentation for the NetObject protocol

NetObject

Declared in:
NetBase.h
Conforms to:
NSObject

This protocol should be implemented by an object used in a connection. When a connection is received by a <NetPort> , the object attached to the port is created and given the transport.

Method summary

connectionEstablished: 

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

Called when a connection has been established, and gives the object the transport used to actually transport the data. aTransport will implement <NetTransport> .


connectionLost 

- (void) connectionLost;

Called when [NetApplication -disconnectObject:] is called with this object as a argument. This object will no longer receive data or other messages after it is disconnected.


dataReceived: 

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

data is data read in from the connection.


transport 

- (id<NetTransport>) transport;

Should return the transport given to the object by -connectionEstablished:


Software documentation for the NetPort protocol

NetPort

Declared in:
NetBase.h
Conforms to:
NSObject

Represents a class that acts as a port. Each port allows a object type to be attached to it, and it will instantiate an object of that type upon receiving a new connection.

Method summary

close 

- (void) close;

Should close the file descriptor.


connectionLost 

- (void) connectionLost;

Called when the object has [NetApplication -disconnectObject:] called on it.


desc 

- (int) desc;

Returns the low-level file descriptor.


newConnection 

- (id) newConnection;

Called when a new connection has been detected by NetApplication . The port should should use this new connection to instantiate a object of the class set by -setNetObject: .


setNetObject: 

- (id) setNetObject: (Class)aClass;

Sets the class of the object that should be attached to the port. This class should implement the <NetObject> protocol.


Software documentation for the NetTransport protocol

NetTransport

Declared in:
NetBase.h
Conforms to:
NSObject

A protocol used for the actual transport class of a connection. A transport is a low-level object which actually handles the physical means of transporting data to the other side of the connection through methods such as -readData: and -writeData: .

Method summary

close 

- (void) close;

Should close the file descriptor.


desc 

- (int) desc;

Returns a file descriptor representing the connection.


isDoneWriting 

- (BOOL) isDoneWriting;

Return YES if no more data is waiting to be written, and NO otherwise. Used by NetApplication to determine when it can stop checking the transport for writing availability.


localHost 

- (id) localHost;

Returns an object representing the local side of a connection. The actual object depends on the implementation of this protocol.


readData: 

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

Called by NetApplication when it is safe to write. Should return data read from the connection with a maximum size of maxReadSize.


remoteHost 

- (id) remoteHost;

Returns an object representing the remote side of a connection. The actual object depends on the implementation of this protocol.


writeData: 

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

This should serve two purposes. When data is not nil, the transport should store the data, and then call [NetApplication -transportNeedsToWrite:] to notify NetApplication that the transport needs to write. When data is nil, the transport should assume that it is actually safe to write the data and should do so at this time. NetApplication will call -writeData: with a nil argument when it is safe to write


Software documentation for the RunLoopEvents protocol

RunLoopEvents

Declared in:
NetBase.h

Used for OS X compatibility. OS X does not have the RunLoopEvents protocol. This is a GNUstep-specific extension. This must be recreated on OS X to compile netclasses.

Method summary

receivedEvent: type: extra: forMode: 

- (void) receivedEvent: (void*)data type: (RunLoopEventType)type extra: (void*)extra forMode: (NSString*)mode;

OS X compatibility function. This is a callback called by the run loop when an event has been received.


timedOutEvent: type: forMode: 

- (NSDate*) timedOutEvent: (void*)data type: (RunLoopEventType)type forMode: (NSString*)mode;

OS X compatibility function. This is a callback called by the run loop when an event has timed out.


NetBase types

RunLoopEventType

typedef enum ... RunLoopEventType;

Used for OS X compatibility. This type is an extension to GNUstep. On OS X, a compatibility layer is created to recreate the GNUstep extensions using OS X extensions.


NetBase variables

FatalNetException

NSString* FatalNetException;

Should be thrown when a non-recoverable exception occurs on a connection. The connection should be closed immediately.


NetException

NSString* NetException;

Thrown when a recoverable exception occurs on a connection or otherwise.



Up