manpagez: man pages & more
man Mac::Carbon(3)
Home | html | info | man
Carbon(3)             User Contributed Perl Documentation            Carbon(3)




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.


INTEL ISSUES

       There are very few issues on Intel.  They mostly center around the fact
       that a Mac four-char-code is often treated as a string in Perl-space,
       but in C-space is an integer.  The conversion process results in
       various errors.

       Four-char-code types include typeType, typeEnumerated, typeProperty,
       typeKeyword, and typeApplSignature.

       There are a few Don't Do Thats to keep in mind.

       o   Don't change the type of an existing AEDesc; coerce it to a new
           desc instead, with AECoerceDesc().  This is generally good advice
           anyway.

       o   Don't pass four-char-codes as arguments to AEBuild*; there's no
           easy way for the called function to know what type the argument is
           going to be passed as, and to fix the data before it is passed.
           Four-char-codes can be literals in AEBuild formats; this is a
           better method to use, when possible.  For example:

                   AEBuild(q{'----':type(@)}, typeProperty);  # don't
                   AEBuild(q{'----':type(prop)});             # do

       o   Similarly, when using AEStream, don't pass a four-char-code to
           WriteData(), if you can avoid it.  Use one of the methods that
           allow type specification (such as WriteDesc and WriteKeyDesc).

       o   Don't try to parse binary data when you don't have to; use the API.
           For example, one of the example files for Mac::Speech parsed the
           creator ID out of the binary data structure instead of calling the
           API, and got the string reversed.


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
           AEDescToSubDesc
           AEGetKeySubDesc
           AEGetNthSubDesc
           AEGetSubDescBasicType
           AEGetSubDescData
           AEGetSubDescType
           AESubDescIsListOrRecord
           AESubDescToDesc
       Mac::Files
           Eject
       Mac::InternetConfig
           ICChooseConfig
           ICChooseNewConfig
           ICGeneralFindConfigFile
           ICGetConfigReference
           ICGetComponentInstance
           ICSetConfigReference
       Mac::Memory
           CompactMemSys
           FreeMemSys
           GetApplLimit
           MaxBlockSys
           MaxBlockSysClear
           MaxMemSys
           NewEmptyHandleSys
           NewHandleSys
           NewHandleSysClear
           NewPtrSys
           NewPtrSysClear
           PurgeMemSys
           ReserveMemSys
       Mac::Processes
           LaunchDeskAccessory
       Mac::Resources
           CreateResFile
           OpenResFile
           RGetResource
       Mac::Sound
           Comp3to1
           Comp6to1
           Exp1to3
           Exp1to6
           MACEVersion
           SndControl
           SndPauseFilePlay
           SndRecordToFile
           SndStartFilePlay
           SndStopFilePlay
           SPBRecordToFile
       MacPerl
           Choose
           ErrorFormat
           FAccess
           LoadExternals
           Quit
           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
           GetProcessPID
           LSFindApplicationForInfo
       Mac::Resources
           FSCreateResourceFile
           FSOpenResourceFile


KNOWN BUGS

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

       o   [GS]etFileInfo() fails on UFS.

       o   GetAliasInfo() fails on UFS and Intel.

       o   Need more tests for:

           Mac::Memory
               Should be more comprehensive for very little-used functions;
               main functionality is tested OK.

           Mac::Sound
               Same.

           Mac::Resources
               Tested really only in other test suites, like Mac::Sound.
               Should be more comprehensive.

           Mac::Components
               Same.

           Mac::Files
               Very good, but could do more exhausative FindFolder() tests.

           Mac::Processes
               Tests not very good, but tested pretty extensively by Mac::Glue
               and friends.

           Mac::MoreFiles
               Same.

           Mac::OSA
               Same.

           Mac::InternetConfig
               No real testing done.

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

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

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

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


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, Emmanuel. M. Decarie, Matthew Drayton, brian d foy,
       David Hand, Gero Herrmann, Peter N Lewis, Paul McCann, Sherm Pendley,
       Randal Schwartz, Michael Schwern, John Siracusa, Dan Sugalksi, Ken
       Williams, Steve Zellers.


SEE ALSO

       perl(1).



perl v5.10.0                      2006-07-06                         Carbon(3)

Mac OS X 10.6 - Generated Thu Sep 17 20:13:27 CDT 2009
© manpagez.com 2000-2025
Individual documents may contain additional copyright information.