Next Previous

Retired Document

Important: This sample code may not represent best practices for current development. The project may use deprecated symbols and illustrate technologies and techniques that are no longer recommended.

MIB-Libraries/NetworkSetup/ReadMe.html

<HTML>

<HEAD>

   <TITLE>Read Me</TITLE>

</HEAD>

<BODY BGCOLOR="#FFFFFF">

<H1>Read Me About MoreNetworkSetup</H1>

<P>1.0b5</P>

<P>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, <STRONG>MoreNetworkSetup</STRONG>, is a

simple wrapper around Network Setup. The second,

<STRONG>NetworkSetupHelpers</STRONG>, 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.</P>

<P>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.</P>

<H2>Packing List</H2>

<P>The sample contains the following items:</P>

<UL>

   <LI>ReadMe.html -- This document.

   <LI>MoreNetworkSetup.h -- Interface to the MoreNetworkSetup

   library.

   <LI>MoreNetworkSetup.c -- Source code for the above.

   <LI>NetworkSetupHelpers.h -- Interface to the NetworkSetupHelpers

   library.

   <LI>NetworkSetupHelpers.c -- Source code for the above.

   <LI>NetworkSetupTest -- A program which tests NetworkSetupHelpers,

   and hence MoreNetworkSetup.

   <LI>Network Setup SDK Bits -- A pre-release copy of the Network

   Setup SDK.

   <LI>OldStyleAPI -- Interfaces and libraries to access the old, not

   supported on Mac OS 8.5 and above, mechanism for changing OT

   configurations.

</UL>

<H2>Using the Sample</H2>

<P>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.</P>

<H2>Building the Sample</H2>

<P>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.</P>

<H2>About the Libraries</H2>

<H3>MoreNetworkSetup</H3>

<P>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.</P>

<P>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 <CODE>NewPtr</CODE> and

<CODE>DisposePtr</CODE>), just go in there and change it.</P>

<P>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.</P>

<H3>NetworkSetupHelpers</H3>

<P>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).</P>

<P>NetworkSetupHelpers provides routines to:</P>

<UL>

   <LI>Enumerate and switch the active TCP/IP, AppleTalk, Remote

   Access and Modem configuration.

   <LI>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.

   <LI>Determine whether opening a TCP/IP endpoint will dial the

   modem.

   <LI>Determine whether AppleTalk is on or off, and also turn it on

   or off.

</UL>

<P>All NetworkSetupHelpers routines work equally well on all Open

Transport-based systems, regardless of whether they have Network

Setup installed on not.</P>

<H2>Using NetworkSetupHelpers</H2>

<P>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.</P>

<H3>Iterating Through Configurations</H3>

<P>The following code shows how to print out all the TCP/IP

configurations on the machine using NetworkSetupHelpers.</P>

<PRE>OSStatus err;

NSHConfigurationListHandle configList;

SInt8 s;

ItemCount i;

&nbsp;

configList = (NSHConfigurationListHandle) NewHandle(0);

&nbsp;

err = NSHGetConfigurationList(kOTTCPv4NetworkConnection, configList);

&nbsp;

s = HGetState( (Handle) configList);

HLock( (Handle) configList );

for (i = 0; i &lt; NSHCountConfigurationList(configList); i++) {

    printf("%#s\n", (*configList)[i].name);

HSetState( (Handle) configList, s);</PRE>

<P>Switching to a configuration is simply a matter of calling

<CODE>NSHSelectConfiguration</CODE> on one of the returned

configurations.</P>

<PRE>err = NSHSelectConfiguration(&amp;(*configList)[0]);</PRE>

<H3>Setting up the Internet</H3>

<P>You can configure the three network protocols required to use the

Internet very simply using <CODE>NSHCreateConfiguration</CODE>.</P>

<PRE>OSStatus err;

NSHConfigurationDigest digest;

NSHConfigurationEntry  newTCPv4Config;

NSHConfigurationEntry  newRemoteConfig;

NSHConfigurationEntry  newModemConfig;

&nbsp;

// Create the TCP/IP configuration.

&nbsp;

OTMemzero(&amp;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

&nbsp;

err = NSHCreateConfiguration(&amp;digest, &amp;newTCPv4Config);

&nbsp;

// Create the Remote Access configuration.

&nbsp;

OTMemzero(&amp;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

&nbsp;

err = NSHCreateConfiguration(&amp;digest, &amp;newRemoteConfig);

&nbsp;

// Create the Modem configuration.

&nbsp;

OTMemzero(&amp;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

&nbsp;

err = NSHCreateConfiguration(&amp;digest, &amp;newModemConfig);

&nbsp;

// Switch the current configuration to the newly created ones.

&nbsp;

err = NSHSelectConfiguration(newTCPv4Config);

err = NSHSelectConfiguration(newRemoteConfig);

err = NSHSelectConfiguration(newModemConfig);</PRE>

<H3>Turning AppleTalk On and Off</H3>

<P>Turning AppleTalk on and off is a single call using

<CODE>NSHSetAppleTalkActive</CODE>:</P>

<PRE>// Turn AppleTalk on.

&nbsp;

err = HSHSetAppleTalkActive(true);

&nbsp;

// Turn it off again.

&nbsp;

err = HSHSetAppleTalkActive(false);</PRE>

<H3>Will Opening a TCP/IP Endpoint Dial the Modem</H3>

<P>This question is answered by a dedicated routine, NSHTCPWillDial.

</P>

<PRE>UInt32 result;

err = NSHTCPWillDial(&amp;result);

&nbsp;

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;

}</PRE>

<H2>Caveats</H2>

<P>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.</P>

<P>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.</P>

<H2>Credits and Version History</H2>

<P>If you find any problems with this sample, mail

&lt;DTS@apple.com&gt; with "Attn: MoreNetworkSetup" as the first line

of your mail and I'll try to fix them up.</P>

<P>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.</P>

<P>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).</P>

<P>1.0b3 (Jul 1999) a limited release with my first cut at the DHCP

release functionality.</P>

<P>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 <CODE>MNGetPrefHandle</CODE> work. Changed

<CODE>MNSGetEntitiesList</CODE> to prevent it dropping a

<CODE>MemError</CODE>.</P>

<P>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.

<CODE>NSHEncodeRemotePassword</CODE> now calls

<CODE>OTCfgEncrypt</CODE> if it's available.

<CODE>NSHTCPWillDial</CODE> now knows that AOL is a dialup port even

though it claims to be an Ethernet port.  Fixed bug in

<CODE>BuildPackedPrefsFromTCPv4ConfigurationDigest</CODE> handling of

<CODE>'isdm'</CODE> preferences.</P>

<P>Share and Enjoy.</P>

<P>Apple Developer Technical Support<BR>

Networking, Communications, Hardware</P>

<P>4 Apr 2000</P>

<P>&nbsp;</P>

</BODY>

</HTML>

Next Previous