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.
Don't change the type of an existing AEDesc; coerce it to a new desc instead, with
AECoerceDesc(). This is generally good advice anyway.
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
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).
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.
[GS]etFileInfo() fails on UFS.
GetAliasInfo() fails on UFS and Intel.
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.
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?
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.8.8 2006-07-06 Carbon(3)
|