TweetFollow Us on Twitter

January 94 - OSL Components

OSL Components

Bo Klintberg

In this crazy, brave, new world of collaboration, Mr. Peabody might suddenly decide to use your application as a server when he's running his amazing new script. Let's have a look at what happens in an application written with MacApp 3 and the OSL Scripting Components source code framework.


Let's begin with how easy it is to create a server application with the OSL Scripting Components package. The only thing that you need to do to create an skeleton server application that supports the Required, Core, Miscellaneous and OSLSC suites is to inherit your application class from TOSLServerApplication and to call IOSLServerApplication from your own TYourApplication::IYourApplication method.
pascal void TScriptServerApplication::IScriptServerApplication()
        kScriptServerMainFileType, kScriptServerAppSignature);


To describe and simplify the concept of an application that communicates in a collaborative environment, I decided to introduce the concept of communication side. As I see it, any application has two communication sides, which may or may not be actively used by the application. One side, the client side, is responsible for the sending of events to other applications and handling the reply coming back. The other side, the server side, is responsible for handling incoming events from other applications and returning a reply (see Figure 1). This figure shows that any application in fact has two communication sides: the Server side and the Client side, thus making it possible to handle incoming messages from client applications, as well as being able to send messages to server applications.

This means that if you want to build your own server (or recorder) application, then you should add a server side to your application; for the developer's convenience, the "normal" cases are already implemented in the OSL Scripting Components package. The following method in TOSLClientServerApplication, the abstract superclass from which TOSLServerApplication and TOSLRecorderApplication inherits, illustrates the main things that an installation of a server side should do.

pascal void TOSLClientServerApplication::DoAddServerSide()

The hooked-up clients manager

First, the DoMakeServerSideNodes method should create a manager for the client nodes that are going to hook up to this server. For example, the result of the DoMakeServerSideNodes method in the TOSLServerApplication class is that it will create a TServerSideManager, which, indeed, manages all hooked-up clients. Each new client that sends an Apple event to such a server application will be added to the TServerSideManager's list of clients.

The Apple events resolver

Second, the DoMakeOSLResolverManager method should create a resolving manager. The resolving manager controls the resolving process when the data received in the Apple event need to be interpreted.

The Apple events handler

Third, the DoAddServerSideBehaviors method should create any number of behaviors to actually dispatch the Apple events. I chose to create one behavior per event suite, thus ending up with adding four behaviors to the TOSLServerApplication: the TReqSuiteHandler (required suite), TCoreSuiteHandler (core suite), TMiscSuiteHandlerForServerSide (Miscellaneous suite) and the TSCSuiteHandlerForServerSide (OSLSC suite).
pascal void TOSLServerApplication::DoAddServerSideBehaviors()


By overriding the DoAddServerSideBehaviors method in your own TYourServerApplication class, you could add any number of suite-dispatching behaviors. You might, for example, want to dispatch any of the other standard suites like the Text suite and Database suite or dispatch the events of your own suite.


Now, let's look at what the application needs to know in order to work as an Apple events server.
  • The 'SIZE' resource must be set up properly
  • Each Apple event suite and its events must be defined
  • There must be dispatching in the code for each Apple event

The 'SIZE' resource

First, you must make sure that your application actually will be delivered an Apple event by the operating system. You do this by setting the highLevelEventAware flag in the 'SIZE' resource of your application. Now, all incoming Apple events can be dispatched in your application.


To prepare a suite's events for dispatching, you need to add two or three resource files, depending on which suite you want to be able to dispatch: a Suite Definition resource, a Command Constants resource, and an AEDispatch resource.

Note, however, that the OSL Scripting Components package already has defined everything you need if you are going to work with the Required, Core, Miscellaneous and OSLSC suites, both the resource files and the actual dispatching code inside the application.

The Suite Definition

A suite definition resource file contains all the constants used by this suite, including the suite ID, event IDs, additional properties and data types and more. If it's a standard suite, like the Required or Core suites, constants for these are already defined in the AppleEvent resource files supplied by Apple. In this case, for example, you won't have to create a RequiredSuite.r or CoreSuite.r resource file.

However, if you are implementing your own suite and your suite's name is, for example, MySuite, then you have to create a MySuite.r resource file, containing constants for the suite ID and the suite's event IDs (see figure 2). This figure shows the three different resource files you'll need to specify and dispatch your own Apple event suite. Note that the constants in the MySuite.r file also will be used if you are creating a client-type application that issues command from your suite.. In the case of the OSL Scripting Components suite, that resource file is named SCSuite.r, and it contains all the constants used by this suite. Remember, this file is not necessarily used only to compile your server application, but could be used to compile your client application as well, if you want that client to issue Apple events from the MySuite suite.

An example of the contents of a Suite Definition resource file: the OSL Scripting Components suite's SCSuite.r:

// OSL Scripting Components suite
#define kOSLScriptingComponentsSuiteEventClass      'SCec'          
#define kSCInformServerThatClientQuits              'SCis'  
#define kSCInformClientThatServerQuits              'SCic'  

The Command Constants

As you may know, MacApp's handling of incoming Apple events is normally to redirect the events so that they will end up in the application class' DoAppleCommand method, ready to be dispatched by you. This means that we must define the command constants that the server's application's DoAppleCommand method (or any of its installed behaviors DoAppleCommand methods) use to dispatch.

In the OSL Scripting Components package, all command constants that are a result of an incoming Apple event are placed in special file for the suite the event belongs to. For example, the command constants that are corresponding to incoming events from the Core suite are placed in the HandleCoreSuiteCommandID.r file.

#define cHandleAEClone             10100
#define cHandleAEClose              10101
#define cHandleAECountElements      10102
Note that all command constants for incoming Apple events begin with "cHandle" to point out that they are on an application's server side.

The Dispatch Table

To actually accomplish the redirection of an Apple event to an Apple command, we must map each event ID to a commandID in a resource of type 'aedt'-apple event dispatch table.

An example of such a resource from the CoreSuiteAEDispatch.r file is shown below, where the constants for the incoming Apple events of the Core suite are mapped to corresponding command constants.

// **********************************************************
// **********************************************************
resource 'aedt' (kAECoreSuiteDispatchTable) {{          
    kAECoreSuite, kAEClone, cHandleAEClone;
    kAECoreSuite, kAEClose, cHandleAEClose;
    kAECoreSuite, kAECountElements, cHandleAECountElements;


Normally, you'd expect to catch the Apple commands in the application's DoAppleCommand method. Well, that's perfectly OK to do, especially if you are going to handle just an event or two. But as soon as you realize that you probably have to support dozens of events from many different suites (including your own suites, too), you may want to look for other ways to do it.

In order to bring some system into this, I decided to work with events on a suite-level basis-that is, a suite and its events is a building block, which I would like to add or remove from the application. To accomplish this, I used the concept of behaviors that I can install into the application. Each behavior contains the handling of all the commands in one suite.

For example, the handling of the Core suite events are done in the behavior called TCoreSuiteHandler, located in the UHandleCoreSuiteCmds unit (see example code below).

pascal void TCoreSuiteHandler::DoAppleCommand(
                   CommandNumber aCmdNumber,
                   const AppleEvent& message,
                   const AppleEvent& reply)    // override
    switch (aCmdNumber)
        case cHandleAEClone:
            case cHandleAEClose:
            case cHandleAECountElements:
                            message, reply);

The DoHandleAECloneCommand, DoHandleAECloseCommand and DoHandleAECountElementsCommand methods in the code example above create, initialize and post a new instance of THandleAECloneCommand, THandleAECloseCommand and THandleAECountElementsCommand, respectively. These server-type command classes (they all inherit from TServerCommand, even though not direct descendants) are also physically located in the UHandleCoreSuiteCmds unit, together with the behavior (see Figure 3).

The server-type command

Each server-type command class has the following main responsibilities:
  1. The TServerCommand-subclass object reads the raw bytes in the event
  2. The TServerCommand hands over these bytes to the Toolbox's AEResolve function
  3. The TServerCommand subclass object asks the resolver manager for the newly resolved TOSLObjectResolver object.
  4. The TServerCommand-subclass object tells the TOSLObjectResolver its message
  5. The TServerCommand-subclass object writes the result back to the client
To be able to manage the complexity of these tasks and to simplify and clarify the responsibilities, I decided to divide the functionality into several subclasses:
  • TOSLServerCommand class
  • THandleAppleEventCommand class
  • THandleOSLObjectCommand class
  • the actual command to handle a specific Apple event, for example the THandleAEGetDataCommand class


This class is responsible for taking care of the type-casting of a TAppleEvent to a TOSLAppleEvent. The TOSLAppleEvent is a subclass of TAppleEvent with a more complete set of routines. The TOSLServerCommand also administrates the automatic registration of the calling client and the deregistering of the client when the communication closes.
class TOSLServerCommand : public TServerCommand
public :
// Creating and freeing:
    virtual pascal void InitializeFromAppleEvent(
                        CommandNumber itsCommandNumber,
                        TCommandHandler* itsContext,
                        Boolean canUndo,
                        Boolean causesChange,
                        TObject* objectToNotify,
                        const AppleEvent& itsMessage,
                        const AppleEvent& itsReply);

    virtual pascal void IOSLServerCommand(
                CommandNumber itsCommandNumber,
                        TCommandHandler* itsContext,
                                         Boolean canUndo,
                                         Boolean causesChange,
                                         TObject* objectToNotify);

// Action:
    virtual pascal void FreeTheMessage();               // override
    virtual pascal void Completed();                    // override
    virtual pascal void RegisterClient();   
    virtual pascal void UnregisterClient(); 


This class is responsible for the main structure of what's going to happen in any Apple event-type command.

The DoReadParameters method calls the GotRequiredParameters and the ReadParameters methods. GotRequiredParameters checks to see if all parameters that are required are OK, while the ReadParameters method is unimplemented (see subclasses).

The DoProcessing method identifies the need for additional processing, but is unimplemented in this class.

This class also identifies the concept of a result, fResultDesc, which can be written to the reply Apple event with the DoWriteReply method. The DoWriteReply method is unimplemented in this class.

class THandleAppleEventCommand : public TOSLServerCommand
// Creating and freeing:
    virtual pascal void Initialize();   // override 
    virtual pascal void Free();         // override
    virtual pascal void DoIt();         // override

// Accessors and mutators:
    virtual pascal CDesc GetResultDesc();
    virtual pascal void SetResultDesc(const CDesc& theResultDesc);

// Action:
    virtual pascal void DoReadParameters();
    virtual pascal void ReadParameters();
    virtual pascal void GotRequiredParameters();

    virtual pascal void DoProcessing();
    virtual pascal void ReportError(OSErr error, long); // override

    virtual pascal void DoWriteReply();

CDesc fResultDesc;


This class is responsible for reading an Apple event containing an object specifier as a direct parameter-something which is quite useful when implementing the Core suite. Also, if it really reads a real object specifier, then that object specifier must be resolved. This facts implies that this class must support the initializing of the resolving process, too.

The reading of the incoming Apple event is done in the ReadDirectObject method. This method also finds out if it's a "real" object specifier (typeObjectSpecifier) or a null specifier (typeNull). If it's a null object specifier, then there's no need for additional resolving; the null value specifies that we found the object tree's root-the application.

If it needs to be resolved, the resolving is initiated by the Toolbox's AEResolve function, which is called from the ResolveObject method. This will initiate the resolving process, which is controlled by the TOSLResolverManager. When the resolving is ready, the DoAfterResolve method is called, which in turn calls the DoTheResolverAction. The DoTheResolverAction is responsible for applying the Apple event verb to the newly resolved resolver object.

class THandleOSLObjectCommand : public THandleAppleEventCommand
// Creating and freeing:
    virtual pascal void Initialize();   // override
    virtual pascal void Free();         // override

// Accessors and mutators:
    virtual pascal Boolean GetCallResolveObject();
    virtual pascal DescType GetDirectObjectType();
    virtual pascal CDesc GetObjectSpecifier();
    virtual pascal TOSLObjectResolver* GetOSLObjectResolver();
    virtual pascal void SetCallResolveObject(
                                Boolean callResolveObject);
    virtual pascal void SetDirectObjectType(D
                                escType theDirectObjectType);
    virtual pascal void SetObjectSpecifier(
                            const CDesc& theObjectSpecifier);
    virtual pascal void SetOSLObjectResolver(
                    TOSLObjectResolver* theOSLObjectResolver);
    virtual pascal void SetShouldCallResolveObject(
                                DescType theDescType);
// Action:
    virtual pascal void DoProcessing();     // override
    virtual pascal void DoBeforeResolve();  
    virtual pascal void DoResolve();
    virtual pascal void DoAfterResolve();   

    virtual pascal void ResetBeforeResolve();
    virtual pascal void ResolveObject();
    virtual pascal void ResolveProperty();
    virtual pascal void CoerceResult();

    virtual pascal OSErr DoTheResolverAction(
                    TOSLObjectResolver* theOSLObjectResolver);

    // Read/Write:
    virtual pascal void ReadParameters();
    virtual pascal void ReadDirectObject();
    virtual pascal void DoWriteReply(); // override

    Boolean fCallResolveObject;     // should we actually do resolve?
    DescType fDirectObjectType;     // either a null aedesc, AEList
                                    // or a obj specifier
    CDesc fObjectSpecifier;             
    TOSLObjectResolver* fOSLObjectResolver;


Now, let's look at the interface of a typical server-type command from the Core suite, the THandleAEGetDataCommand, which inherits from THandleOSLObjectCommand.

The THandleAEGetDataCommand's main responsibility is to override the ReadParameters method to read an additional (and optional) parameter of the Get Data event: its keyAERequestedType parameter.

Another thing it does is to provide an override of the DoTheResolverAction method, which gives the TOSLObjectResolver object (a result of the resolving process) a DoGetData message.

The last thing it does is to coerce the result to the type requested in the keyAERequestedType parameter. This is done in the override of the CoerceResult method.

class THandleAEGetDataCommand : public THandleOSLObjectCommand
// Create / free
    virtual pascal void Initialize();                   // override

// Access:
    virtual pascal DescType GetRequestedType();
    virtual pascal void SetRequestedType(
                            DescType theRequestedType);

// Reading:
    virtual pascal void ReadParameters();               // override
    virtual pascal DescType ReadRequestedType();

// Resolving
    virtual pascal OSErr DoTheResolverAction(
        TOSLObjectResolver* theOSLObjectResolver);      // override
    virtual pascal void CoerceResult();                 // override

    DescType fRequestedType;


Remember ResolveObject, the THandleOSLObjectCommand's method which calls AEResolve? Well, that's the entry point into the resolving process. From that point on, the resolving is managed by the resolving manager until the result, a TOSLObjectResolver object, is delivered back to the command.

The responsibility of the TOSLResolverManager is to manage the process of resolving. There should be only one TOSLResolverManager in an application, and the one provided by the framework is the one you should use-no subclassing is necessary. A typical resolving process goes like this:

First, AEResolve begins its internal resolving mechanism and calls the TOSLResolverManager:CallResolve static function, previously installed by the TOSLResolverManager::InstallAccessors method.

Second, CallResolve calls the TOSLResolverManager:ResolveIt function, which tries to find out which TOSLObjectResolver object the specifier contains. When this first round of resolving is ready, it sets the TOSLResolverManager's field fCurrentOSLObjectResolver to that newly found TOSLObjectResolver object.

Repeat the second step until all contained object resolvers are resolved.

Last, the server-type command retrieves the TOSLObjectResolver object in the TOSLResolverManager's field fCurrentOSLObjectResolver.

Resolver Objects

In the OSL Scripting Components framework, I'm using the concept of resolver objects. A resolver object is an object that is used by the resolving process to access any object's other contained objects (="elements") or any of its properties. Thus, the resolver object defines the properties and containing objects that can be accessed.

A resolver object communicates with its "real" object to get additional information-for example, a TOSLApplicationResolverObject communicates with its TOSLApplication object. What's more, the "real" object is responsible for actually creating the resolver object. This way, you can override the "real" object's class definition to create another resolver object-maybe a simple override of the original one with a couple of new properties and elements?


Let's say that you want to add additional properties for your TYourWindow object (inherited from the TOSLWindow class) when it receives a Get Data Apple event. To do so, you have to make overrides of three classes: the TOSLWindowResolver class, the TOSLWindow class and TOSLApplication class.

Override TOSLWindowResolver to dispatch the new property

The first thing you need to do is to is to override the TOSLWindowResolver class. By using the TOSLWindowResolver class as a base class, you inherit the basic properties of a window according to the Core suite.

Then you have to override the DoGetData method of TOSLWindowResolver. You need to do this because you want the additional pColor property to be dispatched.

pascal OSErr TYourWindowResolver::DoGetData(CDesc& theData)
    DescType propertyID = this->GetPropertyID();
    switch (propertyID)
        case pColor:
            return this->DoGetData_ColorProperty(theData);
            return inherited::DoGetData(theData);

The next thing you need to do is to add a new method in TYourWindowResolver that retrieves the data of that property. Getting the color property from your window object probably should be called DoGetData_ColorProperty. The example below shows you that in that method, you must ask the "real" window for its color property and then ask the "real" window object for its name.

pascal OSErr TYourWindowResolver::DoGetData_ColorProperty
        (CDesc& theData)
    this->FailThisObjectReference(); //is my "real" object valid?
    long aColor = fOSLWindow->OSL_GetData_Color(); 
                                    //color is long in this example
    theData.Create(aColor);         // create a long data descriptor
    return noErr;

Override TOSLWindow to provide a new accessor

You need to override the TOSLWindow class to be able to ask a window for its color. You could name it, for example, TYourWindow. The next thing you need to do is to is to create a new accessor method in TYourWindow that just returns the color of that object.
pascal long TYourWindow::OSL_GetData_Color()
    long theColor = this->GetColor();
    return theColor; // yes, color is a long in this example !

Override TOSLApplication to deliver a TYourWindowResolver

You need to override the NewOSLWindow method of the TOSLApplication class to give the resolving process your own window resolver instead of the standard TOSLWindowResolver otherwise supplied. Now you're ready to go.
pascal TOSLObjectResolver* TYourApplication::NewOSLWindowResolver(
                    TOSLWindow* theOSLWindow,
                    TOSLObjectResolver* theOSLObjectResolver)
if (theOSLWindow)   {
        TYourWindowResolver* aYourWindowResolver =
            new TYourWindowResolver;
        return aYourWindowResolver;
return NULL;

Community Search:
MacTech Search:

Software Updates via MacUpdate

Between 2 Taps - Tap for Tap interview M...
Hello, and welcome back to Between 2 Taps, Tap for Tap’s Indie Dev interview series. [Read more] | Read more »
Facility 47 (Games)
Facility 47 1.0.1 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.1 (iTunes) Description: You wake up alone and freezing in an icy cell. You try the cell door but it’s locked, it seems that you are stuck with no... | Read more »
The best Photoshop alternative on iPad
Instagram and Lightroom are great and all, but sometimes people need to get extra creative with their image editing.Like, Photoshop creative. If you're one of these people, take a look at our pick for the best mobile Photoshop experience on iPad... | Read more »
The Walking Dead: No Man’s Land guide -...
A new update for The Walking Dead: No Man’s Land was released last week, making it the perfect time for you to head back to your base and take out some walkers. Here’s the lowdown on what’s new to the game, and how to take advantage. [Read more] | Read more »
Goat Rider guide - Tips and tricks to st...
We've all been there. One second, we're riding high on a crazed goat, and the next, we've been tossed off it like someone who's no good at goat ridin'. [Read more] | Read more »
Real Boxing 2 CREED: How to become a gre...
Just in time for Rocky fans who can’t wait to see CREED, the latest movie, we have the official tie-in game,Real Boxing 2 CREED. It builds on the success of its predecessor and there’s lots to take in so we at 148apps thought we’d run you through... | Read more »
CoinOp Heroes 2 guide - How to build an...
CoinOp Heroes 2 justlaunched and, like all clickers, it's dangerously addictive stuff. You have to furiously tap your screen to defeat wave after wave of foes and earn an insane amount of cash to spend on character upgrades and an army of minions... | Read more »
Dr. Panda Firefighters (Education)
Dr. Panda Firefighters 1.0.1 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0.1 (iTunes) Description: FIGHT FIRES AND SAVE THE DAY!Work together with Dr. Panda and his firefighting team to rescue his trapped... | Read more »
Puddle + (Games)
Puddle + 1.0 Device: iOS iPhone Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Puddle is back in a new "+" edition featuring enhanced graphics, new videos and Apple TV support ! No IAP and No Ads. Dive into Puddle... | Read more »
Football Manager Mobile 2016 (Games)
Football Manager Mobile 2016 7.0.0 Device: iOS Universal Category: Games Price: $8.99, Version: 7.0.0 (iTunes) Description: Football Manager Mobile 2016 is designed to be played on the move and is the quickest way to manage your... | Read more »

Price Scanner via

Adorama Black Friday deals: Up to $400 off Ma...
Adorama has released their Black Friday deals for 2015. Save up to $400 on MacBook Pros, $200 on MacBooks and MacBook Airs, and $270 on iMacs. Use code RYBFDEAL during checkout to see these prices.... Read more
B&H Photo Deals: $200 off 12-inch 1.2GHz...
In addition to the B&H Photo Black Friday week sales we posted yesterday, B&H has lowered their price on two products to $200 off MSRP: - 12″ 1.2GHz Gray Retina MacBook: $1399 save $200 - 13... Read more
Best Buy Early Access: Today only, Up to $125...
Best Buy has iPad Air 2s on sale for up to $125 off MSRP and Apple Watch models on sale on their online store for up to $100 off MSRP with special codes through midnight CT tonight. Choose free... Read more
UPPERCASE DESIGNS Premium Ultra Thin Keyboard...
UPPERCASE Designs today announced its new Premium Ultra Thin Keyboard Protector and its Palm Rest Protector Set for the 12-inch MacBook. The accessories provide durable protection for the 12-inch... Read more
Al Jazeera Launches New iOS And Android Mobil...
Doha, Qatar based Al Jazeera has launched new mobile and tablet apps on the iOS and Android systems bringing the latest Al Jazeera news and programmes live together with on-demand personalisation.... Read more
B&H Photo Holiday Sale: Up to $250 off Ma...
B&H Photo has all new Macs on sale for up to $500 off MSRP as part of their Holiday sale including free shipping plus NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1799 $200 off - 15″ 2.... Read more
Free Aura ‘Ultimate’ Mac App For Gmail Update...
Miami, Florida based Crosscoded has announced Aura 1.2.0, an update to the Mac app for Gmail. Aura mixes the power of a native client with the flexibility of the Gmail web app with support for up to... Read more
Apple Will Edge Closer to Samsung in Smartpho...
Total smartphone shipments for 2015 are projected to decline by 9.7% to 1.286 billion units, according to the latest report from global market research firm TrendForce. Though Chinese vendors have... Read more
Sidefari – Split Screen Multitasking In Safar...
Francisco Cantu’s Sidefari is a simple web browser designed to act as a companion to Safari on the iPad. With multitasking in iOS 9, Sidefari uses the new Safari View Controller to show an extra... Read more
12-inch MacBooks in stock for up to $120 off,...
Adorama has 12″ Retina MacBooks in stock for up to $120 off MSRP including free shipping plus NY & NJ sales tax only. For a limited time, Adorama will include a free Apple USB-C to USB Adapter,... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Merchant Operations Manager: *Apple* Pay -...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more than Read more
*Apple* Pay QA Manager - Apple Inc. (United...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more than Read more
Sr Software Engineer *Apple* Pay - Apple In...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more than Read more
Hardware Systems Architect - *Apple* Watch...
# Hardware Systems Architect - Apple Watch Job Number: 38449977 Santa Clara Valley, Califo ia, United States Posted: Apr. 16, 2015 Weekly Hours: **Job Summary** The Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.