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.

MoreOpenTransport/ReadMeOTClassicContext.html

<HTML>

<HEAD>

   <TITLE>Read Me</TITLE>

</HEAD>

<BODY BGCOLOR="#FFFFFF">

<H1>Read Me About OTClassicContext</H1>

<P>1.0b4</P>

<P>OTClassicContext provides the glue necessary to call the Carbon

"InContext" Open Transport APIs in an InterfaceLib environment. The

goal is to allow you to build a Carbon and non-Carbon application (or

extension) from the same source base without conditional

compilation.</P>

<P>Open Transport tracks assets, like memory and endpoints, in a very

Byzantine fashion. See DTS Technote 1173 <A HREF="http://developer.apple.com/technotes/tn/tn1173.html">Understanding

Open Transport Asset Tracking</A> for a full description. To make

this clearer Carbon introduced a new set of Open Transport APIs, with

the suffix "InContext", which explicitly describe the context to

which assets are assigned. For example, in Carbon you must call

<CODE>OTOpenEndpointInContext</CODE> rather than

<CODE>OTOpenEndpoint</CODE> so that the system knows which client

owns the endpoint.</P>

<P>The main problem with this technique is that it is hard to

maintain a source base that compiles for both Carbon and non-Carbon

applications and extensions. This glue is a way around that

problem.</P>

<P>The glue in this sample supports PowerPC code compiled for OT

1.1.1 and above. See the <A HREF="#Caveats">Caveats</A> section for

an explanation of these restrictions.</P>

<P>A future version of the OT SDK will contain a final release of

this glue.</P>

<H2>Packing List</H2>

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

<UL>

   <LI>ReadMeOTClassicContext.html -- This document.</LI>

   <LI>OTClassicContext.h -- Most of the important "InContext" APIs

   are defined in the standard Open Transport headers. However, some

   APIs that logically operate within a context are not defined in

   the Open Transport headers because they are not part of Carbon. If

   you're building non-Carbon code you may need access to these APIs,

   so they are defined in this file.</LI>

   <LI>OpenTransportClientPPC.o -- The OT classic context glue

   itself. Use this version for your production builds.</LI>

   <LI>OpenTransportClientPPC.debug.o -- The OT classic context glue

   itself. Use this version for your debug builds.</LI>

   <LI>OTClassicContextTest -- A simple program that was used to test

   the glue.</LI>

</UL>

<H2>Using the Glue</H2>

<P>To use this glue within your project, take the following

steps.</P>

<OL>

   <LI>Remove any Open Transport "PPC.o" files from your project.

   This includes "OpenTransportAppPPC.o", "OpenTransportExtnPPC.o",

   "OpenTptATalkPPC.o", "OpenTptInetPPC.o", "OpenTptUtilsAppPPC.o",

   and "OpenTptUtilsExtnPPC.o", and their debug variants.</LI>

   <LI>Add the "OpenTransportClientPPC.o" file to your production

   build and "OpenTransportClientPPC.debug.o" to your debug

   build.</LI>

   <LI>Convert your source code to use the "InContext" versions of

   the Open Transport routines that create assets. See the Carbon

   documentation for details on these routines. If you use routines

   that create assets that aren't part of Carbon, for example

   <CODE>OTStreamOpen</CODE>, you must include "OTClassicContext.h"

   in your source.</LI>

</OL>

<H2><A NAME=Caveats></A>Caveats</H2>

<P>You should be aware of the caveats associated with this glue.</P>

<UL>

   <LI>This glue only works for PowerPC binaries. Making this work

   for 68K binaries would be tricky because OT uses ASLM linkage for

   68K code.</LI>

   <LI>This glue only works for OT 1.1.1 and above. Earlier version

   of OT used a slightly different linkage scheme for client code.

   This should not be a limitation unless you were previously linking

   with "OpenTptClientCompat11PPC.o".</LI>

   <LI>This library does not let you initialize just the Open

   Transport utilities. There is no equivalent of calling

   <CODE>InitOpenTransportUtilities</CODE>, a call which is much

   misunderstood. What it does is create a client connection to Open

   Transport without loading the OT kernel. This reduced memory usage

   in old machines where certain OT components might want to use OT

   utilities without loading the entire OT kernel into memory. On

   modern systems the OT kernel is always loaded (either because OT

   doesn't unload the kernel any more, or because the kernel was

   loaded at system startup by one of many potential network

   clients), so this restriction should not cause any problems.</LI>

   <LI>If you connect to Open Transport using this glue you no longer

   have access to ASLM functions. In general this is A Good Thing

   (tm).</LI>

   <LI>The glue does not support the UNIX-style OT entry points (for

   example, <CODE>t_open</CODE>). In general this is a A Good Thing

   (tm), although retrofitting that capability would be relatively

   easy.</LI>

   <LI>The fact that a routine is declared "InContext" does not

   necessarily guarantee that OT tracks the asset created by that

   routine. For example, OT on traditional Mac OS does not currently

   track deferred tasks, timer tasks, system tasks, or raw streams.

   &#91;As an aside, the OT compatibility library in Mac OS X does

   track these assets.&#93; The "InContext" routine just provides a

   way for a future version of OT to track those assets.</LI>

   <LI>Certain OT utility routines, listed below, are implemented in

   the statically linked OT libraries. If you link with this glue you

   will not be able to use those routines. Fortunately, most of these

   routines are sufficiently obscure that this does not present a

   serious problem.<TABLE BORDER=1 WIDTH=300>

      <TR>

         <TD>

            <PRE>OTLoadCFMLibrary</PRE>

         </TD>

      </TR>

      <TR>

         <TD>

            <PRE>OTGetCFMSymbol</PRE>

         </TD>

      </TR>

      <TR>

         <TD>

            <PRE>OTGetCFMPointer</PRE>

         </TD>

      </TR>

      <TR>

         <TD>

            <PRE>OTFindCFMLibraries</PRE>

         </TD>

      </TR>

      <TR>

         <TD>

            <PRE>OTReleaseCFMConnection</PRE>

         </TD>

      </TR>

      <TR>

         <TD>

            <PRE>OTHoldThisCFMLibrary</PRE>

         </TD>

      </TR>

      <TR>

         <TD>

            <PRE>OTUnholdThisCFMLibrary</PRE>

         </TD>

      </TR>

      <TR>

         <TD>

            <PRE>OTLoadASLMLibrary</PRE>

         </TD>

      </TR>

      <TR>

         <TD>

            <PRE>OTUnloadASLMLibrary</PRE>

         </TD>

      </TR>

      <TR>

         <TD>

            <PRE>InitASLMForCFMLibrary</PRE>

         </TD>

      </TR>

      <TR>

         <TD>

            <PRE>TeardownASLMForCFMLibrary</PRE>

         </TD>

      </TR>

      <TR>

         <TD>

            <PRE>TrapAvailable</PRE>

         </TD>

      </TR>

      <TR>

         <TD>

            <P>other miscellaneous C and C++ runtime routines</P>

         </TD>

      </TR>

   </TABLE>

   </LI>

</UL>

<H2>Credits and Version History</H2>

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

&lt;DTS@apple.com&gt; and I'll try to fix them up.</P>

<P>1.0b1 (Sep 2000) was distributed to a small number of Apple

engineers for review purposes.</P>

<P>1.0b2 (Oct 2000) was distributed to a small number of Apple

engineers for review purposes. The glue is now included as an object

file rather than source code.</P>

<P>1.0b3 (Oct 2000) was the first released version. The name of the

object file has changed to better match the future OT SDK

version.</P>

<P>1.0b4 (Dec 2000) fixes <CODE>InitOpenTransportInContext</CODE> to

accept nil for the <CODE>outClientContext</CODE> parameter..</P>

<P>Share and Enjoy.</P>

<P>Apple Developer Technical Support<BR>

Networking, Communications, Hardware</P>

<P>13 Dec 2000</P>

<P>&nbsp;</P>

</BODY>

</HTML>

Next Previous