ACS Network suite:
Internet Overview

 

The Network suite is part of the Apple Class Suites (ACS) library. The Internet portion of the Network suite provides support for TCP connections and Internet Domain Name Resolution services. It also provides several convenience classes for receiving events from objects based on the CTCPConnection_AC and CInternetHost_AC classes, as well as the class CSimpleHTTPServer_AC, whose main function is to provide an example of a Network Strategy.

Addressing

Addressing is handled with the CInternetAddress_AC class, which is a subclass of CNetworkAddress_AC. Setting with and converting to a string are fully supported. This class stores an IP address and port number.

TCP Connections

You initiate a TCP connection with the CTCPConnector_AC class, which is a subclass of CConnector_AC. The CTCPConnector_AC subclass adds the ability to use CInternetAddress_AC to specify which server to connect with (CConnector_AC uses CNetworkAddress). CTCPConnector_AC also adds the ability to specify which host to connect to with a host name string. This causes the CTCPConnector_AC class to automatically do a name to address resolution before connecting.

You accept a connection with the CTCPAcceptor_AC class. This class currently adds no API to its CAcceptor_AC superclass.

You send data across a TCP connection with the CTCPConnection_AC class. All of the network transactions defined in the general portion of the Network suite (see the Network release notes for more information) will work with CTCPConnection_AC. CTCPConnection_AC is a subclass of CServiceHandler_AC with a few additions, including methods to set the maximum number of concurrent TCP connections and methods to see how many CTCPConnection_ACs are currently connected.

Domain Name Resolution (DNR)

DNR services are handled with the CInternetHost_AC class. This class stores a host name, and from one to a handful (if the host is multi-homed) of IP addresses.

To perform resolution asynchronously, use the ResolveAddressToNameSync or ResolveNameToAddressAsync methods. You must either register an event receiver to receive the appropriate event (see the Event Receiving section below) or spin a thread and poll the state of the CInternetHost_AC until it is resolved.

You can also perform resolution synchronously with ResolveAddressToNameSync or ResolveNameToAddressSync. Both methods are thread-savvy and yield to other threads if appropriate.

To resolve name to address, call SetHostName with the host name and then call either ResolveNameToAddressAsync or ResolveNameToAddressSync. If the Internet host returns successfully, it returns from one to several (if the host is multi-homed) addresses. You can determine the number of hosts by calling the GetNumAddresses method; the GetAddress method has an index parameter for getting each host.

To resolve address to name, call SetAddress (be sure to set address at index zero) with an IP address, and then call ResolveNameToAddressAsync or ResolveNameToAddressSync.

Note: If no CReactor_AC is specified, CInternetHost_AC will create one using the default CReactorFactory_AC (see the Patterns suite release notes).

Event Receiving

The Network suite provides two convenience mixin classes for receiving events, MInternetHostEventReceiver_AC and MTCPConnectionEventReceiver_AC. You can mix these classes in to any object and have that object receive events from the corresponding type of event sender. Note that for each instance of the sending object, your object must register for events (see the Patterns suite release notes for more details).

Example:
class CFoo : public MInternetHostEventReceiver_AC
{
	...
	virtual void AddressToNameResolved(CInternetHost_AC* inHost)
	{
		outStream << "The address resolved to " << inHost->GetHostName();
	}
 
	virtual void NameToAddressResolved(CInternetHost_AC* inHost);
	{
		// Note this only gets the first address if it's multi-homed.
		CInternetAddress_AC address = inHost->GetAddress();
		outStream << "The address resolved to " << address.GetAsString();
	}
};
 
CFoo foo;
CRefCountingPtr_AC<CInternetHost_AC> host = foo.CreateInternetHost();
host->SetHostName("www.apple.com");
host->ResolveNameToAddress(); 
	// this will output to the outStream when it receives an event
							
host->SetAddress(CInternetAddress_AC("17.254.3.62"));
host->ResolveAddressToName(); 
	// this will output to the outStream when it receives an event

Managers

The Network suite provides two CServiceHandler_AC manager classes, CMultiTCPConnectionManager_AC and CSingleTCPConnectionManager_AC*. These classes manage CTCPConnection_AC objects for you, as described above in the Manager section of the Network release notes.

CTCPSocket_AC*

This class allows Java-inspired, thread-savvy, blocking network calls for initiating and accepting TCP connections, and easy streaming of outgoing and incoming data.

* A nonfinal version of this class should ship in the late breaking folder with MacApp R13. More detailed release notes about CTCPSocket_AC will be provided in the same location.

Miscellaneous

The class CInternetUtils_AC provides a mechanism for provider-specific calls such as converting an IP address to a string containing the ASCII version of the IP address. All of the API is used by other higher level classes, such as CInternetAddress_AC, so you will probably never have to call it directly.

The class CInternetHostRep_AC is the base class for the provider-specific implementation of the CInternetHost_AC class, and isn't relevant to normal use of the CInternetHost_AC.

The file MacOSInternet.cp contains the hooks into the native provider code specific to Internet support (see the Miscellaneous section in the Network release notes for more information).