Inside Macintosh: Networking With Open Transport / Part 1 - Open Transport Essentials

Chapter 2 - Getting Started With Open Transport

Initializing Open Transport

The first step in using Open Transport is to initialize it, and the most practical and efficient way to do that is to call the InitOpenTransport function just before you need to call any Open Transport functions. Note that only the client calling Open Transport functions needs to initialize it or close it.

When you initialize Open Transport, it initializes data structures that it needs so that you can call Open Transport functions. An error is returned if Open Transport cannot be used. The following code sample illustrates how you might initialize Open Transport from an application and how you might close it down again upon termination.

void main(void)
{
   Boolean gOTInited;
   gOTInited = ( InitOpenTransport() == noErr );

   /* The rest of your application goes here.*/
   if (gOTInited) {
      CloseOpenTransport();
      gOTInited = false;
   }
}

Note

If your application needs to manipulate ports or call
Open Transport utility functions but it does not need
to open or use any providers, you can call the function InitOpenTransportUtilities instead of the function InitOpenTransport.

Open Transport consists of several parts: the Open Transport kernel, Open Transport utilities, AppleTalk, and TCP/IP. Which of these parts are loaded into memory depends partly on control panel settings and partly on actions you take:

• AppleTalk is loaded if the user has activated it in the control panel. If the user has not activated AppleTalk, it is not possible to load it programmatically.

• TCP/IP is loaded in one of two ways. If the user activates it in the control panel and checks "Load Only When Needed" (the default), TCP/IP is loaded when you open a TCP/IP endpoint or a TCP/IP service provider. If the user activates TCP/IP and checks "Load Only When Needed," TCP/IP is loaded at start-up. If the user does not activate TCP/IP in the control panel, it is not possible to load it programmatically.

• The Open Transport kernel is loaded when AppleTalk or TCP/IP is loaded or when you call the InitOpenTransport function.

• The Open Transport utilities are always loaded. You still need to call the function InitOpenTransportUtilities to register yourself as an Open Transport client if you want to get or change port information without loading the Open Transport kernel.

Initializing From a Client Application

If you are writing an application, you must follow these steps before you can call any Open Transport functions:

1. Include the Open Transport client header file, OpenTransport.h.

2. Call the InitOpenTransport function (or the InitOpenTransportUtilities function if only accessing port information).

3. Link with the appropriate libraries as described in "Open Transport Libraries".

Note

68000 applications do not need to explicitly establish an A5 world before calling Open Transport nor do they need to reset their A5 world before each call to an Open Transport function. This is all done automatically for them. (PowerPC applications never need to be concerned about establishing an A5 world.)

Initializing From a Stand-Alone Code Resource

If you are writing a stand-alone code resource or a shared library, you must follow these steps before calling any Open Transport functions:

1. Include the Open Transport client header file, OpenTransport.h.

2. Establish an A5 world if you are writing 68000 code; see the Apple Shared Library Manager Developer's Guide for details on how to do this. (Stand-alone 68000 code resources must ensure that their A5 world is correct each time they call an Open Transport function.)

3. Call the InitOpenTransport function (or the InitOpenTransportUtilities function).

4. Call the CloseOpenTransport function when finished.

5. Link with the appropriate libraries as described in "Open Transport Libraries". Remember that a code resource or shared library should link with the "Extn" variants of the libraries.

Using ASLM and Open Transport

Open Transport is based on ASLM and initializes this manager itself. But if your 68000 application uses ASLM, you must

• call the InitLibraryManager function before calling the InitOpenTransport function

• call the CloseLibraryManager function after calling the CloseOpenTransport function.

This is true for both applications, shared libraries, and stand-alone resources. For applications the ExitToShell trap will be patched so that the close calls are executed whether you call them explicitly or not. For stand-alone code, you must call the close calls yourself.

Using the Gestalt Function to Determine Whether Open Transport Is Available

If you are writing an installer, you might want to know if Open Transport is available on your computer. To do this, call the Gestalt function with 'otan' as its selector. If Gestalt returns no error and its response parameter returns with a value other than 0, Open Transport is available. To find out whether AppleTalk, TCP, or NetWare are present, you can examine the response parameter bits. For a list of the possible bit values, see "The Gestalt Selector and Response Bits".

For version 1.1 or later of Open Transport, you can use the Gestalt function with the 'otvr' selector to determine the Open Transport version in NumVersion format. For more information on Apple's version numbering scheme and the NumVersion format, see Technote OV12: Version Territory.

Note

If your application uses Open Transport, it should determine whether it is present using the InitOpenTransport function. Do not use Gestalt for this. The InitOpenTransport functionperforms all the right checks for you.

---

Subtopics

Initializing From a Client Application

Initializing From a Stand-Alone Code Resource

Using ASLM and Open Transport

Using the Gestalt Function to Determine Whether Open Transport Is Available