Read Me About MoreNetworkSetup

1.0b5

Mac OS 8.5 introduced a new programming interface, Network Setup, that allows you to programmatically configure the network interfaces on the machine (AppleTalk, TCP/IP, Remote Access, etc). This sample includes two source code libraries which provide simplified access to Network Setup. The first, MoreNetworkSetup, is a simple wrapper around Network Setup. The second, NetworkSetupHelpers, provides high-level functionality (for example, turning AppleTalk on/off, switching TCP/IP configurations) that works with both Network Setup and on pre-Mac OS 8.5 systems.

The MoreNetworkSetup library requires the Network Setup Extension (which is installed by Mac OS 8.5 and above). NetworkSetupHelpers works with both Mac OS 8.5 and later (using the Network Setup programming interface) and older systems (using a previously undocumented programming interface). NetworkSetupHelpers requires Open Transport 1.1.1 or higher.

Packing List

The sample contains the following items:

• ReadMe.html -- This document.
• MoreNetworkSetup.h -- Interface to the MoreNetworkSetup library.
• MoreNetworkSetup.c -- Source code for the above.
• NetworkSetupHelpers.h -- Interface to the NetworkSetupHelpers library.
• NetworkSetupHelpers.c -- Source code for the above.
• NetworkSetupTest -- A program which tests NetworkSetupHelpers, and hence MoreNetworkSetup.
• Network Setup SDK Bits -- A pre-release copy of the Network Setup SDK.
• OldStyleAPI -- Interfaces and libraries to access the old, not supported on Mac OS 8.5 and above, mechanism for changing OT configurations.

Using the Sample

To use this sample, open the "NetworkSetupTest" folder and launch the NetworkSetupTest appliation. The program offers you a number of interactive choices, as well as the option to run some automated tests.

Building the Sample

The sample was built using the standard MoreIsBetter build environment (CodeWarrior Pro 2 compiler with Universal Interfaces 3.2). You should be able to build the project in Code Warrior Pro 4 without difficulty. To build the project, open the "NetworkSetupTest.mcp" project file inside the "NetworkSetupTest" folder, select the "Fat" target, and choose Make from the Project menu. This will build NetworkSetupTest-68K, NetworkSetupTest-PPC, and NetworkSetupTest.

About the Libraries

MoreNetworkSetup

MoreNetworkSetup is a simple layer on top of Network Setup. Because of its history, Network Setup is somewhat more complex that it needs to be. MoreNetworkSetup reduces that complexity.

One way MoreNetworkSetup reduces complexity is that it allocates memory for you. Network Setup never allocates memory and returns it to you. It's an entirely pointer-based programming interface. This makes sense for a system library which may be used in a variety of contexts. MoreNetworkSetup can relax this restriction because we give you the source code. If you need to change the memory allocator (currently the Mac OS Memory Manager's NewPtr and DisposePtr), just go in there and change it.

To understand MoreNetworkSetup, you'll probably need a high-level overview of Network Setup itself. The documentation for Network Setup is still in progress, although the "NetworkSetupBigPicture.html" should help a bit.

NetworkSetupHelpers

The philosophy behind NetworkSetupHelpers is that it should provide a high-level abstraction to commonly needed features of Network Setup. It should also provide that abstraction on both Mac OS 8.5 (where Network Setup is installed) and older systems (through a previously undocumented API).

NetworkSetupHelpers provides routines to:

• Enumerate and switch the active TCP/IP, AppleTalk, Remote Access and Modem configuration.
• Create, duplicate, read, write, delete and rename TCP/IP, Remote Access and Modem configurations. This is the core functionality of any Internet setup assistant program.
• Determine whether opening a TCP/IP endpoint will dial the modem.
• Determine whether AppleTalk is on or off, and also turn it on or off.

All NetworkSetupHelpers routines work equally well on all Open Transport-based systems, regardless of whether they have Network Setup installed on not.

Using NetworkSetupHelpers

The routines in NetworkSetupHelpers are very easy to use. The "NetworkSetupTest.c" source file includes examples of how to use the various routines. However, it's worth repeating some of these examples here.

Iterating Through Configurations

The following code shows how to print out all the TCP/IP configurations on the machine using NetworkSetupHelpers.

OSStatus err;
NSHConfigurationListHandle configList;
SInt8 s;
ItemCount i;
 
configList = (NSHConfigurationListHandle) NewHandle(0);
 
err = NSHGetConfigurationList(kOTTCPv4NetworkConnection, configList);
 
s = HGetState( (Handle) configList);
HLock( (Handle) configList );
for (i = 0; i < NSHCountConfigurationList(configList); i++) {
    printf("%#s\n", (*configList)[i].name);
}
HSetState( (Handle) configList, s);

Switching to a configuration is simply a matter of calling NSHSelectConfiguration on one of the returned configurations.

err = NSHSelectConfiguration(&(*configList)[0]);

Setting up the Internet

You can configure the three network protocols required to use the Internet very simply using NSHCreateConfiguration.

OSStatus err;
NSHConfigurationDigest digest;
NSHConfigurationEntry  newTCPv4Config;
NSHConfigurationEntry  newRemoteConfig;
NSHConfigurationEntry  newModemConfig;
 
// Create the TCP/IP configuration.
 
OTMemzero(&digest, sizeof(digest));
digest.fTCPv4.fProtocol = kOTTCPv4NetworkConnection;
PLstrcpy(digest.fTCPv4.fConfigName, "\pMy TCP/IP Config");
digest.fTCPv4.fPortRef = 0x000c0005; // should really look up "IPCP" in the OT port registry
digest.fTCPv4.fConfigMethod = kTCPv4ManualConfig;
digest.fTCPv4.fIPAddress = 0;      // PPP will negotiate address with server
digest.fTCPv4.fSubnetMask = 0;     // PPP will negotiate address with server
// fill out remaining fields of digest
 
err = NSHCreateConfiguration(&digest, &newTCPv4Config);
 
// Create the Remote Access configuration.
 
OTMemzero(&digest, sizeof(digest));
digest.fRemote.fProtocol = kOTRemoteNetworkConnection;
PLstrcpy(digest.fRemote.fConfigName, "\pMy Remote Access Config");
digest.fRemote.fGuestLogin = false;
digest.fRemote.fPasswordValid = true;
PLstrcpy(digest.fRemote.fUserName, "\pQuinn");
PLstrcpy(digest.fRemote.fPassword, "\pPassword");
PLstrcpy(digest.fRemote.fPhoneNumber, "\p555-1234");
// fill out remaining fields of digest
 
err = NSHCreateConfiguration(&digest, &newRemoteConfig);
 
// Create the Modem configuration.
 
OTMemzero(&digest, sizeof(digest));
digest.fModem.fProtocol = kOTModemNetworkConnection;
PLstrcpy(digest.fModem.fConfigName, "\pMy Modem Config");
digest.fModem.fPortRef = 0x0009ff0a; // should really look up "IPCP" in the OT port registry
// fill out remaining fields of digest
 
err = NSHCreateConfiguration(&digest, &newModemConfig);
 
// Switch the current configuration to the newly created ones.
 
err = NSHSelectConfiguration(newTCPv4Config);
err = NSHSelectConfiguration(newRemoteConfig);
err = NSHSelectConfiguration(newModemConfig);

Turning AppleTalk On and Off

Turning AppleTalk on and off is a single call using NSHSetAppleTalkActive:

// Turn AppleTalk on.
 
err = HSHSetAppleTalkActive(true);
 
// Turn it off again.
 
err = HSHSetAppleTalkActive(false);

Will Opening a TCP/IP Endpoint Dial the Modem

This question is answered by a dedicated routine, NSHTCPWillDial.

UInt32 result;
err = NSHTCPWillDial(&result);
 
switch (result) {
    case kNSHTCPDialUnknown:
        // couldn't get an answer
        break;
    case kNSHTCPDialTCPDisabled:
        // TCP/IP is currently disabled
        break;
    case kNSHTCPDialYes:
        // definitely will dial
        break;
    case kNSHTCPDialNo:
        // definitely won't dial
        break;
}

Caveats

The Network Setup programming interface is only available to PowerPC code. If the Network Setup library is available, you should always use it in preference to whatever old mechanism you're using. Therefore, if you base code on this sample, you must ensure that it runs as PowerPC code on PowerPC computers.

One possible workaround to this is to call the Network Setup programming interface from your 68K code via Mixed Mode. While this is possible, this sample doesn't include the relevant glue. If you run a 68K build of this code on a machine with Network Setup installed, it will detect that case and return an error.

Credits and Version History

If you find any problems with this sample, mail <DTS@apple.com> with "Attn: MoreNetworkSetup" as the first line of your mail and I'll try to fix them up.

1.0b1 (Nov 1998) was the first released version. It's based on a number of other samples that use Network Setup, including OTTCPWillDial and SwitchTCP.

1.0b2 (May 1999) is a sigificant update that includes the Internet setup routines (the ability to create, duplicate, read, write, delete and rename TCP/IP, Remote Access and Modem configurations).

1.0b3 (Jul 1999) a limited release with my first cut at the DHCP release functionality.

1.0b4 (Oct 1999) is a minor update that fixes a number of bugs. Fixed some comments in "NetworkSetupHelpers.h". Fixed a bug that prevented "NetworkSetupHelpers.c" from creating MacIP configurations. Fixed a bug that prevented you from selecting a newly created configuration. Made MNGetPrefHandle work. Changed MNSGetEntitiesList to prevent it dropping a MemError.

1.0b5 (Apr 2000) is a minor update to sync up with the new "NetworkSetup.h" from Universal Interfaces 3.3.1 and to fix some minor bugs and add some minor features. NSHEncodeRemotePassword now calls OTCfgEncrypt if it's available. NSHTCPWillDial now knows that AOL is a dialup port even though it claims to be an Ethernet port. Fixed bug in BuildPackedPrefsFromTCPv4ConfigurationDigest handling of 'isdm' preferences.

Share and Enjoy.

Apple Developer Technical Support
Networking, Communications, Hardware

4 Apr 2000