The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Mac-Carbon-0.65
River stage one • 2 direct dependents • 2 total dependents
1 ++
/ Mac::Carbon

NAME

Mac::Carbon - Access to Mac OS Carbon API

SYNOPSIS

        use Mac::Carbon;
        use Mac::Carbon qw(:files :morefiles);

DESCRIPTION

This module provides documentation of the Mac::Carbon modules, and acts as a frontend to them.

Mac::Carbon is a collection of perl modules for accessing the Carbon API under Mac OS X. It is a port of the Toolbox modules written by Matthias Neeracher for MacPerl.

This module will load in all the Carbon modules, and export all of the functions, constants, and other variables. An export tag is set up for each module, so they may be selected individually.

This module exists primarily because in Mac OS X, all the Carbon functions are imported into a C program with a single header, Carbon.h, so Mac OS X users may prefer to load in the entire Carbon API with a single module.

For detailed information on the Carbon API (highly recommended, as a familiarity with Carbon is assumed in the POD), see apple.com.

        http://developer.apple.com/techpubs/macosx/Carbon/

The documentation is also located on your system, if you have the Developer Tools installed, at /Developer/Documentation/Carbon/.

Also of significant use are the related header files on your system. Use the `locate` command to find them. They contain current documentation and notes for the API.

The modules were written for Mac OS originally, and are in part being ported to Carbon. You may also be interested in the original documentation.

        http://developer.apple.com/techpubs/macos8/

TOOLBOX MAPPINGS

Swiped from Mac/Toolbox.pod in the MacPerl distribution.

The Macintosh Operating System provides a rich API with thousands of toolbox calls. The MacPerl toolbox modules aim to make as much as possible of this functionality available to MacPerl programmers. The mapping of the toolbox interfaces into MacPerl is intended to be

  1. Convenient to use for Perl programmers.

  2. As close as possible to the C interfaces.

This translates into a mapping strategy which is discussed in the following sections.

Function mappings

MacPerl toolbox calls take their input arguments in the same order as the corresponding toolbox functions. Output arguments are never passed by reference, but returned from the calls. If there are several output arguments, a list is returned. If an error occurs, the function returns undef or () and the error code is available in the $^E variable.

        $port = GetPort();
        SetPort($port);
        $desc = AECreateDesc("TEXT", "Hello, World") or die $^E;

Data structure mappings

Complex data structures are mapped into blessed references. Data fields are available through member functions which return the value of a field if called without an argument and change the value if called with an argument.

        $rect = Rect->new(10, 20, 110, 220);
        $rect->top;
        $rect->right(250);

MAC OS X DIFFERENCES

The modules follow the same API under Mac OS X as Mac OS, except that the non-Carbon API is not supported (for example, NewHandle is supported, but NewHandleSys is not). Calling a function not supported by Carbon will generate an exception.

In each module's documentation, functions that work only under Mac OS (non-Carbon) are marked with Mac OS only. Those that work only under Mac OS X (Carbon) are marked with Mac OS X only. A complete list is at the end of this document.

The MacPerl package is automatically bootstrapped in MacPerl; it is included here, though the app-specific functions (Reply, Quit) are not supported, and the MacPerl package must be loaded explicitly (e.g., use MacPerl;). Also, Ask/Answer/Pick are provided via AppleScript, talking to the SystemUIServer process.

The Mac-specific error codes are put in $^E as in MacPerl, but $^E does not automatically convert the numeric error into a string in string context. See brian d foy's Mac::Errors module on the CPAN for this:

        use Mac::Errors '$MacError';
        my $info1 = FSpGetCatInfo($file1) or die $^E + 0;    # error number
        my $info2 = FSpGetCatInfo($file2) or die $MacError;  # error string

Mac::Errors is not included with or required by Mac::Carbon, but it is highly recommended.

$! is set at the same time $^E is set. This is different behavior from MacPerl, but similar to other platforms. On MacPerl, $^E is signed, and on Unix it is unsigned, so to get the numeric value from $^E, just add 0, as above. Could be worse.

Files are passed back and forth using Unix/POSIX filespecs (if you care about the gory details, a portion of the GUSI API has been reimplemented here, and it handles the conversions). Similarly, times are converted back and forth from the Mac OS epoch to the Unix epoch.

The support functions are in Carbon.h. See that file for descriptions of the issues, including bugs and possibilities for bugs, involved.

KNOWN BUGS

See http://rt.cpan.org/NoAuth/Bugs.html?Dist=Mac-Carbon for more information.

  • Make test suite work without access to main console.

  • [GS]etFileInfo fails on UFS.

  • Need more tests for Mac::Components, Mac::MoreFiles, Mac::Resources, Mac::InternetConfig, Mac::Processes, Mac::Sound.

  • In a few places, we need to know a text encoding, and assume it (such as in LSFindApplicationForInfo(), where Latin-1 is assumed). This is likely incorrect.

  • FSSpecs are limited to 31 characters. Ugh. Provide access to newer FSRef-based APIs.

  • Not specific to the Carbon versions: the Mac:: modules define classes such as Handle which probably should be something else, like Mac::Handle or Mac::Carbon::Handle or Mac::Memory::Handle (other examples include AEDesc, Point, Rect). No one has really complained before except on principle, but still ...

  • Can we support XCMDs etc. via XL? Do we want to?

PACKAGES AND EXPORT TAGS

See each individual module for more information on use. See README for more information about modules not included here.

        Mac::AppleEvents        appleevents
        Mac::Components         components
        Mac::Files              files
        Mac::Gestalt            gestalt
        Mac::InternetConfig     internetconfig
        Mac::Memory             memory
        Mac::MoreFiles          morefiles
        Mac::Notification       notification
        Mac::OSA                osa     
        Mac::Processes          processes
        Mac::Resources          resources
        Mac::Sound              sound
        Mac::Speech             speech
        Mac::Types              types
        MacPerl                 macperl

UNSUPPORTED FUNCTIONS

Functions supported only in Mac OS

The functions below are supported only in Mac OS, and not in Mac OS X, either because they are not supported by Carbon, or make no sense on Mac OS X.

Mac::AppleEvents::AECountSubDescItems
Mac::AppleEvents::AEDescToSubDesc
Mac::AppleEvents::AEGetKeySubDesc
Mac::AppleEvents::AEGetNthSubDesc
Mac::AppleEvents::AEGetSubDescBasicType
Mac::AppleEvents::AEGetSubDescData
Mac::AppleEvents::AEGetSubDescType
Mac::AppleEvents::AESubDescIsListOrRecord
Mac::AppleEvents::AESubDescToDesc
Mac::Files::Eject
Mac::InternetConfig::ICChooseConfig
Mac::InternetConfig::ICChooseNewConfig
Mac::InternetConfig::ICGeneralFindConfigFile
Mac::InternetConfig::ICGeneralFindConfigFile
Mac::InternetConfig::ICGetComponentInstance
Mac::InternetConfig::ICSetConfigReference
Mac::Memory::CompactMemSys
Mac::Memory::FreeMemSys
Mac::Memory::GetApplLimit
Mac::Memory::MaxBlockSys
Mac::Memory::MaxBlockSysClear
Mac::Memory::MaxMemSys
Mac::Memory::NewEmptyHandleSys
Mac::Memory::NewHandleSys
Mac::Memory::NewHandleSysClear
Mac::Memory::NewPtrSys
Mac::Memory::NewPtrSysClear
Mac::Memory::PurgeMemSys
Mac::Memory::ReserveMemSys
Mac::Processes::LaunchDeskAccessory
Mac::Resources::CreateResFile
Mac::Resources::OpenResFile
Mac::Resources::RGetResource
Mac::Sound::Comp3to1
Mac::Sound::Comp6to1
Mac::Sound::Exp1to3
Mac::Sound::Exp1to6
Mac::Sound::MACEVersion
Mac::Sound::SndControl
Mac::Sound::SndPauseFilePlay
Mac::Sound::SndRecordToFile
Mac::Sound::SndStartFilePlay
Mac::Sound::SndStopFilePlay
Mac::Sound::SPBRecordToFile
MacPerl::ErrorFormat
MacPerl::FAccess
MacPerl::LoadExternals
MacPerl::Quit
MacPerl::Reply

Functions supported only in Mac OS X

The functions below are supported only in Mac OS X, and not in Mac OS, either because they are newer APIs, or make no sense on Mac OS.

Mac::Processes::GetProcessForPID
Mac::Processes::GetProcessPID
Mac::Processes::LSFundApplicationForInfo
Mac::Resources::FSCreateResourceFile
Mac::Resources::FSOpenResourceFile

AUTHOR

The Mac Toolbox modules were written by Matthias Neeracher <neeracher@mac.com>. They were ported to Mac OS X and are currently maintained by Chris Nandor <pudge@pobox.com>.

THANKS

Michael Blakeley <mike@blakeley.com>, Emmanuel. M. Decarie <emm@scriptdigital.com>, Matthew Drayton <matthew@stairways.com.au>, brian d foy <comdog@panix.com>, David Hand <davidhand@davidhand.com>, Gero Herrmann <herr@ils.uec.ac.jp>, Peter N Lewis <peter@stairways.com.au>, Paul McCann <pmccann@maths.adelaide.edu.au>, Randal Schwartz <merlyn@stonehenge.com>, John Siracusa <siracusa@mindspring.com>, Dan Sugalksi <dan@sidhe.org>, Ken Williams <ken@mathforum.org>, Steve Zellers.

SEE ALSO

perl(1).