The Network suite is part of the Apple Class Suites (ACS) library. The first release of Network Suite provides support for TCP connections and Internet DNR services only. The Network suite can use either MacTCP or Open Transport (chosen at runtime), although Open Transport is recommended.
The suite is divided into four APIs: the general, Internet, MacTCP, and Open Transport APIs. Most clients of the ACS suite will only have to deal with the General and Internet APIs. The MacTCP and Open Transport implementation is provided as a simplifying layer of abstraction. The programmer doesn't have to know anything about Open Transport or MacTCP to use the Network suite. As a result, these release notes will concentrate on the General APIs. For information on the Internet API, see the Internet release notes.
The most important service-handler class is CServiceHandler_AC. This class is used to send and receive data over the network. Conceptually, this can be anything from a TCP connection to a UDP session or an ADSP (Appletalk) connection. The class is called a service handler because it manages a CService_AC object, which is the abstraction used to represent the actual connection or session. For example, the CMacTCPConnection_AC is a subclass of CService_AC for handling MacTCP connections. Remember that the CServiceHandler_AC will create the proper CService_AC class for you. You don't have to know which provider-specific service (MacTCP, Open Transport, etc.) you will need to instantiate&endash;you just interact with the CServiceHandler_AC object.
To send and receive data through a CServiceHandler_AC object, you use a subclass of the CNetworkTransaction_AC class. A CServiceHandler_AC object manages a queue of CNetworkTransaction_AC objects, so you can queue up as many transactions as you'd like. Several subclasses of CNetworkTransaction_AC are provided, including CFileSender_AC, CFileReceiver_AC, CDataSender_AC, CDataReceiver_AC, CHangup_AC, and CDisconnect_AC.
For connections of any type, you use a CConnector_AC object to initiate the connection or a CAcceptor_AC object to listen for and receive connections. When these objects successfully initiate or accept a connection, control of the connection is passed to a CServiceHandler_AC so that you can send or receive data (the CServiceHandler_AC object may be created or passed to the acceptor or connector depending on the situation). The actual work of the acceptor or connector is done by a provider-specific subclass of CServiceAcceptor_AC or CServiceConnector_AC (remember that a service is the provider-specific object that sends and receives data). An example of a CServiceConnector_AC is the COTConnector_AC. Again, you don't need to create or interact with the service objects at all. You simply use the CConnector_AC or CAcceptor_AC objects to set up the connection (you'll actually deal with protocol-specific subclasses of these, such as CTCPConnector_AC), and the CServiceHandler_AC object to send or receive data.
For managing address types, the Network suite provides the CNetworkAddress_AC abstraction. You will generally deal with a subclass of CNetworkAddress_AC, such as CTCPConnection_AC, but network addresses can be set by and converted to text if you are dealing with a CNetworkAddress_AC.
The Network suite uses the event subsystem in the Patterns suite (see the Patterns suite release notes) to pass events. All of the important networking classes are subclasses of MEventTransceiver_AC, so classes you define that descend from these classes can receive events.
Several classes are provided with the Networking suite to make receiving events simpler. The most important of these is MTemplatedServiceEventReceiver_AC. This class is templated on the type of service handler, such as CTCPConnection_AC, that is expected to be sending events. Most of the methods of MTemplatedServiceHandler_AC have a SERVICE_HANDLER parameter, so that when the class is expanded with a specific subclass of CServiceHandler_AC, as shown in the following example, the methods will be type safe.
Example: class MyClass : public MTemplatedServiceEventReceiver_AC<CTCPConnection_AC> { public: virtual void ReceiveData(CTCPConnection_AC* inConnection, ...); }; OR class MyOtherClass : public MTemplatedServiceEventReceiver_AC<CUDPSession_AC> { // CUDPSession_AC is a planned feature. public: virtual void ReceiveData(CUDPSession_AC* inSession, ...); };
The Networking suite's general API provides a ready-made base class for receiving events from the object CServiceHandler_AC called MServiceEventReceiver_AC. This class can be valuable if you're dealing with service handlers polymorphically, that is to say, the same code can deal with a CTCPConnection_AC, CUDPSession_AC, or CADSPConnection_AC because the parameter to the overridable functions takes a CServiceHandler_AC.
Example: void CMyApp::PrepareToReceiveData(CServiceHandler* inHandler) { // inHandler can be a CTCPConnection_AC, CUDPSession_AC, etc. ... }
All of the network event IDs, such as kNullEvent, kSentData, and kReceivedData, are defined in the file "NetEvents_AC.h".
Managing a CServiceHandler_AC can be a bit of work. For example, an unexpected error may occur or a connection may suddenly be terminated. To help you deal with this complexity, the Network suite provides the "Manager" abstraction&endash;classes that provide default management for CServiceHandler_AC objects. The base class for these Manager classes is CAbstractServiceHandlerManager_AC. Additional manager classes include CMultiConnectionManager_AC and CSingleConnectionManager_AC. These classes are subclasses of CEventRouter_AC (see the Patterns suite release notes) so you can subscribe to events from them and the Manager class will also respond to each event you receive.
For example, when you receive an event indicating that a connection has been completed, the connection manager may put the connection's CServiceHandler_AC into a list. If all you need to do is notify the user, or send data, or so on, you can use the pointer to the CServiceHandler_AC and forget about keeping track of it because you know the Manager class is managing it for you, for example, the typical manager class will store the service handler in a list and then delete it when the connection or session is closed. When moments occur that are important in the life of the service handler&endash;data arriving, connection terminated, and so on&endash;an event will be sent that corresponds to a method that can be overridden, such as "ConnectionTerminated".
A strategy is a set of rules, such as the FTP protocol, for sending and receiving data. The class CNetworkStrategy_AC provides an abstraction for creating and using strategies in the Network suite. For example, Webinator (the HTTP server sample application) creates a CSimpleHTTPServer_AC strategy class and installs it into a CTCPMultiConnectionManager_AC object, creating an HTTP server with just a few lines of code. You can create many different types of strategy classes and just drop them in (even at runtime) anywhere, with any kind of protocol or any kind of network session.
Hooks into the native provider code are located in the file MacOSProvider_AC.cp. Currently, only MacTCP and Open Transport are provided. They depend on the compile time flags, qWantsMacTCP_AC and qWantsOpenTransport_AC. The methods for the classes that support MacTCP and Open Transport are defined in separate files from the usual parent class .cp file in order to facilitate cross platform support, i.e. different files can be linked in for different platforms. Future plans call for a WinProvider.cp file with hooks for WinSock.
The file OSNetSwitches_AC.h is another cross platform file, in which the default flags for a platform are declared. The default values for qWantsMacTCP and qWantsOpenTransport_AC for the Mac OS are defined there.
Global network values are stored in the class CNetGlobals_AC. Currently, only the default timeout value is defined there.