1.0b4
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.
The sample contains the following items:
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.
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.
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.
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:
All NetworkSetupHelpers routines work equally well on all Open Transport-based systems, regardless of whether they have Network Setup installed on not.
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.
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]);
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 is a single call using
NSHSetAppleTalkActive:
// Turn AppleTalk on. err = HSHSetAppleTalkActive(true); // Turn it off again. err = HSHSetAppleTalkActive(false);
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;
}
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.
If you find any problems with this sample, mail <DTS@apple.com> with "Attn: Quinn" 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.
Share and Enjoy.
Quinn "The Eskimo!"
Apple Developer Technical Support
Networking, Communications, Hardware
1 Oct 1999