692 lines
21 KiB
C
692 lines
21 KiB
C
/*
|
|
File: Scrap.h
|
|
|
|
Contains: Scrap Manager Interfaces.
|
|
|
|
Version: QuickTime 7.3
|
|
|
|
Copyright: (c) 2007 (c) 1985-2001 by Apple Computer, Inc., all rights reserved
|
|
|
|
Bugs?: For bug reports, consult the following page on
|
|
the World Wide Web:
|
|
|
|
http://developer.apple.com/bugreporter/
|
|
|
|
*/
|
|
#ifndef __SCRAP__
|
|
#define __SCRAP__
|
|
|
|
#ifndef __MIXEDMODE__
|
|
#include <MixedMode.h>
|
|
#endif
|
|
|
|
#ifndef __MACERRORS__
|
|
#include <MacErrors.h>
|
|
#endif
|
|
|
|
#ifndef __CFSTRING__
|
|
#include <CFString.h>
|
|
#endif
|
|
|
|
|
|
|
|
#if PRAGMA_ONCE
|
|
#pragma once
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#if PRAGMA_IMPORT
|
|
#pragma import on
|
|
#endif
|
|
|
|
#if PRAGMA_STRUCT_ALIGN
|
|
#pragma options align=mac68k
|
|
#elif PRAGMA_STRUCT_PACKPUSH
|
|
#pragma pack(push, 2)
|
|
#elif PRAGMA_STRUCT_PACK
|
|
#pragma pack(2)
|
|
#endif
|
|
|
|
/*
|
|
________________________________________________________________
|
|
UNIVERSAL SCRAP MANAGER INTERFACES
|
|
________________________________________________________________
|
|
The following interfaces are available when compiling for BOTH
|
|
Carbon AND Mac OS 8.
|
|
________________________________________________________________
|
|
*/
|
|
/*
|
|
While we're in here mucking about, we defined a new type to
|
|
to put some confusion to rest. The old calls, as well as the
|
|
new calls, use the new type. Existing clients should be
|
|
blissfully ignorant.
|
|
*/
|
|
|
|
typedef FourCharCode ScrapFlavorType;
|
|
/*
|
|
Newsflash! After 15 years of arduous toil, it's finally possible
|
|
for specially trained typists wielding advanced text editing
|
|
technology to define symbolic names for commonly used scrap
|
|
flavor type constants! Apple triumphs again!
|
|
*/
|
|
enum {
|
|
kScrapFlavorTypePicture = FOUR_CHAR_CODE('PICT'), /* contents of a PicHandle*/
|
|
kScrapFlavorTypeText = FOUR_CHAR_CODE('TEXT'), /* stream of characters*/
|
|
kScrapFlavorTypeTextStyle = FOUR_CHAR_CODE('styl'), /* see TEGetStyleScrapHandle*/
|
|
kScrapFlavorTypeMovie = FOUR_CHAR_CODE('moov'), /* reference to a movie*/
|
|
kScrapFlavorTypeSound = FOUR_CHAR_CODE('snd '), /* see SndRecord and SndPlay*/
|
|
kScrapFlavorTypeUnicode = FOUR_CHAR_CODE('utxt'), /* stream of UTF16 characters*/
|
|
kScrapFlavorTypeUnicodeStyle = FOUR_CHAR_CODE('ustl') /* ATSUI defines; Textension uses*/
|
|
};
|
|
|
|
/*
|
|
If you are a Carbon client and you need to run on Mac OS 8,
|
|
you may still need to load and unload the scrap. Under Mac OS
|
|
X, the scrap is held by the pasteboard server instead of in a
|
|
handle in your app's heap, so LoadScrap and UnloadScrap do
|
|
nothing when called under Mac OS X.
|
|
*/
|
|
|
|
/*
|
|
* LoadScrap()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: in InterfaceLib 7.1 and later
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
LoadScrap(void) ONEWORDINLINE(0xA9FB);
|
|
|
|
|
|
/*
|
|
* UnloadScrap()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: in InterfaceLib 7.1 and later
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
UnloadScrap(void) ONEWORDINLINE(0xA9FA);
|
|
|
|
|
|
#if CALL_NOT_IN_CARBON
|
|
/*
|
|
________________________________________________________________
|
|
MAC OS 8 SCRAP MANAGER INTERFACES
|
|
________________________________________________________________
|
|
The following interfaces are available only when compiling for
|
|
plain vanilla Mac OS 8. We didn't add comments to them because
|
|
Inside Mac covers them in detail.
|
|
________________________________________________________________
|
|
*/
|
|
struct ScrapStuff {
|
|
SInt32 scrapSize;
|
|
Handle scrapHandle;
|
|
SInt16 scrapCount;
|
|
SInt16 scrapState;
|
|
StringPtr scrapName;
|
|
};
|
|
typedef struct ScrapStuff ScrapStuff;
|
|
typedef ScrapStuff * PScrapStuff;
|
|
typedef ScrapStuff * ScrapStuffPtr;
|
|
#endif /* CALL_NOT_IN_CARBON */
|
|
|
|
#if CALL_NOT_IN_CARBON
|
|
/*
|
|
* InfoScrap()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: in InterfaceLib 7.1 and later
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API( ScrapStuffPtr )
|
|
InfoScrap(void) ONEWORDINLINE(0xA9F9);
|
|
|
|
|
|
/*
|
|
* GetScrap()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: in InterfaceLib 7.1 and later
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API( long )
|
|
GetScrap(
|
|
Handle destination,
|
|
ScrapFlavorType flavorType,
|
|
SInt32 * offset) ONEWORDINLINE(0xA9FD);
|
|
|
|
|
|
/*
|
|
* ZeroScrap()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: in InterfaceLib 7.1 and later
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
ZeroScrap(void) ONEWORDINLINE(0xA9FC);
|
|
|
|
|
|
/*
|
|
* PutScrap()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: in InterfaceLib 7.1 and later
|
|
* CarbonLib: not available
|
|
* Mac OS X: not available
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
PutScrap(
|
|
SInt32 sourceBufferByteCount,
|
|
ScrapFlavorType flavorType,
|
|
const void * sourceBuffer) ONEWORDINLINE(0xA9FE);
|
|
|
|
|
|
|
|
/*
|
|
________________________________________________________________
|
|
CARBON SCRAP MANAGER INTERFACES
|
|
________________________________________________________________
|
|
The following interfaces are available only when compiling for
|
|
Carbon.
|
|
________________________________________________________________
|
|
*/
|
|
|
|
/*
|
|
When promising a scrap flavor, it's OK if you
|
|
don't yet know how big the flavor data will be.
|
|
In this case, just pass kScrapFlavorSizeUnknown
|
|
for the flavor data size.
|
|
*/
|
|
|
|
#endif /* CALL_NOT_IN_CARBON */
|
|
|
|
enum {
|
|
kScrapFlavorSizeUnknown = -1
|
|
};
|
|
|
|
/*
|
|
kScrapReservedFlavorType is a flavor type which is reserved
|
|
for use by Scrap Manager. If you pass it to Scrap Manager,
|
|
it will be rejected.
|
|
*/
|
|
|
|
enum {
|
|
kScrapReservedFlavorType = FOUR_CHAR_CODE('srft')
|
|
};
|
|
|
|
/*
|
|
We've added scrap flavor flags ala Drag Manager.
|
|
|
|
kScrapFlavorMaskNone means you want none of the flags.
|
|
|
|
kScrapFlavorSenderOnlyMask means only the process which
|
|
put the flavor on the scrap can see it. If some other
|
|
process put a flavor with this flag on the scrap,
|
|
your process will never see the flavor, so there's
|
|
no point in testing for this flag.
|
|
|
|
kScrapFlavorTranslated means the flavor was translated
|
|
from some other flavor in the scrap by Translation Manager.
|
|
Most callers should not care about this bit.
|
|
*/
|
|
enum {
|
|
kScrapFlavorMaskNone = 0x00000000,
|
|
kScrapFlavorMaskSenderOnly = 0x00000001,
|
|
kScrapFlavorMaskTranslated = 0x00000002
|
|
};
|
|
|
|
typedef UInt32 ScrapFlavorFlags;
|
|
/*
|
|
ScrapFlavorInfo describes a single flavor within
|
|
a scrap.
|
|
*/
|
|
struct ScrapFlavorInfo {
|
|
ScrapFlavorType flavorType;
|
|
ScrapFlavorFlags flavorFlags;
|
|
};
|
|
typedef struct ScrapFlavorInfo ScrapFlavorInfo;
|
|
typedef struct OpaqueScrapRef* ScrapRef;
|
|
/*
|
|
kScrapRefNone is guaranteed to be an invalid ScrapRef. This
|
|
is convenient when initializing application variables.
|
|
*/
|
|
#define kScrapRefNone ((ScrapRef)NULL)
|
|
/*
|
|
Defined Apple scrap names for GetScrapByName
|
|
kScrapClipboardScrap traditional clipboard scrap
|
|
kScrapFindScrap compatible with Cocoa's global find scrap
|
|
*/
|
|
#define kScrapClipboardScrap CFSTR("com.apple.scrap.clipboard")
|
|
#define kScrapFindScrap CFSTR("com.apple.scrap.find")
|
|
|
|
/* Enumerated options to be passed to GetScrapByName*/
|
|
|
|
enum {
|
|
kScrapGetNamedScrap = 0, /* get current named scrap without bumping*/
|
|
kScrapClearNamedScrap = (1L << 0) /* acquire the named scrap, bumping and clearing*/
|
|
};
|
|
|
|
/*
|
|
GetScrapByName allows access to an indefinite number of public or private
|
|
scraps. The constant kScrapClipboardScrap refers to the "current" scrap
|
|
we've all come to know and love. kScrapFindScrap allows Carbon apps to
|
|
interact seamlessly with Cocoa's global find scrap. Note that calling:
|
|
|
|
GetScrapByName( kScrapClipboardScrap, kScrapGetNamedScrap, &scrap );
|
|
|
|
is an exact match to the call:
|
|
|
|
GetCurrentScrap( &scrap );
|
|
|
|
Additionally, a call to:
|
|
|
|
GetScrapByName( kScrapClipboardScrap, kScrapClearNamedScrap, &scrap );
|
|
|
|
is a replacement for the sequence:
|
|
|
|
ClearCurrentScrap();
|
|
GetCurrentScrap( &scrap );
|
|
|
|
You can use this API to generate your own private scraps to use as a high
|
|
level interprocess communication between your main and helper apps. The Java
|
|
naming convention is suggested for your scraps ( ie. com.joeco.scrap.secret ).
|
|
|
|
CarbonLib does not support arbitrary named scraps; when calling this API on
|
|
CarbonLib, kScrapClipboardScrap is the only supported value for the name parameter.
|
|
*/
|
|
/*
|
|
* GetScrapByName()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.5 and later
|
|
* Mac OS X: in version 10.1 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
GetScrapByName(
|
|
CFStringRef name,
|
|
OptionBits options,
|
|
ScrapRef * scrap);
|
|
|
|
|
|
/*
|
|
GetCurrentScrap obtains a reference to the current scrap.
|
|
The ScrapRef obtained via GetCurrentScrap will become
|
|
invalid and unusable after the scrap is cleared.
|
|
*/
|
|
|
|
/*
|
|
* GetCurrentScrap()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
GetCurrentScrap(ScrapRef * scrap);
|
|
|
|
|
|
/*
|
|
GetScrapFlavorFlags tells you [a] whether the scrap contains
|
|
data for a particular flavor and [b] some things about that
|
|
flavor if it exists. This call never blocks, and is useful
|
|
for deciding whether to enable the Paste item in your Edit
|
|
menu, among other things.
|
|
*/
|
|
|
|
/*
|
|
* GetScrapFlavorFlags()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
GetScrapFlavorFlags(
|
|
ScrapRef scrap,
|
|
ScrapFlavorType flavorType,
|
|
ScrapFlavorFlags * flavorFlags);
|
|
|
|
|
|
/*
|
|
GetScrapFlavorSize gets the size of the data of the specified
|
|
flavor. This function blocks until the specified flavor
|
|
data is available. GetScrapFlavorSize is intended as a prelude
|
|
to allocating memory and calling GetScrapFlavorData.
|
|
*/
|
|
|
|
/*
|
|
* GetScrapFlavorSize()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
GetScrapFlavorSize(
|
|
ScrapRef scrap,
|
|
ScrapFlavorType flavorType,
|
|
Size * byteCount);
|
|
|
|
|
|
/*
|
|
GetScrapFlavorData gets the data from the specified flavor in the
|
|
specified scrap. This function blocks until the specified flavor
|
|
data is available. Specify the maximum size your buffer can contain;
|
|
on output, this function produces the number of bytes that were
|
|
available (even if this is more than you requested).
|
|
*/
|
|
|
|
/*
|
|
* GetScrapFlavorData()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
GetScrapFlavorData(
|
|
ScrapRef scrap,
|
|
ScrapFlavorType flavorType,
|
|
Size * byteCount,
|
|
void * destination);
|
|
|
|
|
|
/*
|
|
ClearCurrentScrap clears the current scrap. Call this
|
|
first when the user requests a Copy or Cut operation --
|
|
even if you maintain a private scrap! You should not wait
|
|
until receiving a suspend event to call ClearCurrentScrap. Call
|
|
it immediately after the user requests a Copy or Cut operation.
|
|
You don't need to put any data on the scrap immediately (although
|
|
it's perfectly fine to do so). You DO need to call GetCurrentScrap
|
|
after ClearCurrentScrap so you'll have a valid ScrapRef to pass
|
|
to other functions.
|
|
*/
|
|
|
|
/*
|
|
* ClearCurrentScrap()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
ClearCurrentScrap(void);
|
|
|
|
|
|
/*
|
|
ClearScrap will clear the scrap passed in and return the bumped
|
|
ScrapRef value. ClearScrap behaves similarly to GetScrapByName
|
|
when called with the kScrapClearNamedScrap option with the
|
|
benefit of not requiring a name in the event one is not available.
|
|
|
|
CarbonLib does not support arbitrary named scraps; when calling this
|
|
API on CarbonLib, only clearing the current scrap is supported.
|
|
*/
|
|
/*
|
|
* ClearScrap()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.5 and later
|
|
* Mac OS X: in version 10.1 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
ClearScrap(ScrapRef * inOutScrap);
|
|
|
|
|
|
|
|
/*
|
|
PutScrapFlavor is a lot like PutScrap, with two differences:
|
|
we added a ScrapRef parameter at the beginning and you can
|
|
"promise" various aspects of a flavor. If you pass a NIL
|
|
data pointer, this is a promise that in the future you
|
|
will provide data for this flavor. Provide the data
|
|
through a subsequent call to PutScrapFlavor, either later
|
|
in the same code flow or during a scrap promise keeper proc.
|
|
If you know how big the data is, you can pass the size as
|
|
well, and this may allow subsequent callers of GetScrapFlavorInfo
|
|
to avoid blocking. If you don't know the size, pass -1.
|
|
If you pass a 0 size, you are telling Scrap Manager not to
|
|
expect any data for this flavor. In this case, the flavor
|
|
data pointer is ignored. NOTE: the last time you can provide
|
|
scrap flavor data is when your scrap promise keeper gets
|
|
called. It is NOT possible to call PutScrapFlavor while
|
|
handling a suspend event; suspend events under Carbon
|
|
simply don't work the way they do under Mac OS 8.
|
|
|
|
The method for setting Scrap Manager promises differs from that for Drag Manger promises.
|
|
This chart describes the method for setting scrap promises via PutScrapFlavor().
|
|
|
|
dataPtr dataSize result
|
|
pointer value actual data size The data of size dataSize pointed to by dataPtr is added to the scrap.
|
|
0 actual data size A promise for data of size dataSize is placed on the scrap.
|
|
0 -1 A promise for data of an undetermined size is placed on the scrap.
|
|
ignored 0 A flavor with no data expected is placed on the scrap. This is not a promise.
|
|
*/
|
|
/*
|
|
* PutScrapFlavor()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
PutScrapFlavor(
|
|
ScrapRef scrap,
|
|
ScrapFlavorType flavorType,
|
|
ScrapFlavorFlags flavorFlags,
|
|
Size flavorSize,
|
|
const void * flavorData); /* can be NULL */
|
|
|
|
|
|
/*
|
|
ScrapPromiseKeeper is a function you write which is called by
|
|
Scrap Manager as needed to keep your earlier promise of a
|
|
particular scrap flavor. When your function is called, deliver
|
|
the requested data by calling PutScrapFlavor.
|
|
*/
|
|
|
|
typedef CALLBACK_API( OSStatus , ScrapPromiseKeeperProcPtr )(ScrapRef scrap, ScrapFlavorType flavorType, void *userData);
|
|
typedef STACK_UPP_TYPE(ScrapPromiseKeeperProcPtr) ScrapPromiseKeeperUPP;
|
|
/*
|
|
* NewScrapPromiseKeeperUPP()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: available as macro/inline
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( ScrapPromiseKeeperUPP )
|
|
NewScrapPromiseKeeperUPP(ScrapPromiseKeeperProcPtr userRoutine);
|
|
#if !OPAQUE_UPP_TYPES
|
|
enum { uppScrapPromiseKeeperProcInfo = 0x00000FF0 }; /* pascal 4_bytes Func(4_bytes, 4_bytes, 4_bytes) */
|
|
#ifdef __cplusplus
|
|
inline DEFINE_API_C(ScrapPromiseKeeperUPP) NewScrapPromiseKeeperUPP(ScrapPromiseKeeperProcPtr userRoutine) { return (ScrapPromiseKeeperUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppScrapPromiseKeeperProcInfo, GetCurrentArchitecture()); }
|
|
#else
|
|
#define NewScrapPromiseKeeperUPP(userRoutine) (ScrapPromiseKeeperUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppScrapPromiseKeeperProcInfo, GetCurrentArchitecture())
|
|
#endif
|
|
#endif
|
|
|
|
/*
|
|
* DisposeScrapPromiseKeeperUPP()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: available as macro/inline
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( void )
|
|
DisposeScrapPromiseKeeperUPP(ScrapPromiseKeeperUPP userUPP);
|
|
#if !OPAQUE_UPP_TYPES
|
|
#ifdef __cplusplus
|
|
inline DEFINE_API_C(void) DisposeScrapPromiseKeeperUPP(ScrapPromiseKeeperUPP userUPP) { DisposeRoutineDescriptor((UniversalProcPtr)userUPP); }
|
|
#else
|
|
#define DisposeScrapPromiseKeeperUPP(userUPP) DisposeRoutineDescriptor(userUPP)
|
|
#endif
|
|
#endif
|
|
|
|
/*
|
|
* InvokeScrapPromiseKeeperUPP()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: available as macro/inline
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( OSStatus )
|
|
InvokeScrapPromiseKeeperUPP(
|
|
ScrapRef scrap,
|
|
ScrapFlavorType flavorType,
|
|
void * userData,
|
|
ScrapPromiseKeeperUPP userUPP);
|
|
#if !OPAQUE_UPP_TYPES
|
|
#ifdef __cplusplus
|
|
inline DEFINE_API_C(OSStatus) InvokeScrapPromiseKeeperUPP(ScrapRef scrap, ScrapFlavorType flavorType, void * userData, ScrapPromiseKeeperUPP userUPP) { return (OSStatus)CALL_THREE_PARAMETER_UPP(userUPP, uppScrapPromiseKeeperProcInfo, scrap, flavorType, userData); }
|
|
#else
|
|
#define InvokeScrapPromiseKeeperUPP(scrap, flavorType, userData, userUPP) (OSStatus)CALL_THREE_PARAMETER_UPP((userUPP), uppScrapPromiseKeeperProcInfo, (scrap), (flavorType), (userData))
|
|
#endif
|
|
#endif
|
|
|
|
#if CALL_NOT_IN_CARBON || OLDROUTINENAMES
|
|
/* support for pre-Carbon UPP routines: New...Proc and Call...Proc */
|
|
#define NewScrapPromiseKeeperProc(userRoutine) NewScrapPromiseKeeperUPP(userRoutine)
|
|
#define CallScrapPromiseKeeperProc(userRoutine, scrap, flavorType, userData) InvokeScrapPromiseKeeperUPP(scrap, flavorType, userData, userRoutine)
|
|
#endif /* CALL_NOT_IN_CARBON */
|
|
|
|
/*
|
|
SetScrapPromiseKeeper associates a ScrapPromiseKeeper with a
|
|
scrap. You can remove a ScrapPromiseKeeper from a scrap by
|
|
passing a NIL ScrapPromiseKeeper to SetScrapPromiseKeeper.
|
|
Pass whatever you like in the last parameter; its value will
|
|
be passed to your ScrapPromiseKeeper, which can do whatever
|
|
it likes with the value. You might choose to pass a pointer
|
|
or handle to some private scrap data which the
|
|
ScrapPromiseKeeper could use in fabricating one or more
|
|
promised flavors.
|
|
*/
|
|
/*
|
|
* SetScrapPromiseKeeper()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
SetScrapPromiseKeeper(
|
|
ScrapRef scrap,
|
|
ScrapPromiseKeeperUPP upp,
|
|
const void * userData);
|
|
|
|
|
|
/*
|
|
GetScrapFlavorCount produces the number of
|
|
items which can be obtained by GetScrapFlavorInfoList.
|
|
*/
|
|
|
|
/*
|
|
* GetScrapFlavorCount()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
GetScrapFlavorCount(
|
|
ScrapRef scrap,
|
|
UInt32 * infoCount);
|
|
|
|
|
|
/*
|
|
GetScrapFlavorInfoList fills a list (array)
|
|
of items which each describe the corresponding
|
|
flavor in the scrap. It fills no more array
|
|
elements as are specified. On exit, it produces
|
|
the count of elements it filled (which may be
|
|
smaller than the count requested). Yes, YOU
|
|
must provide the memory for the array.
|
|
*/
|
|
|
|
/*
|
|
* GetScrapFlavorInfoList()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
GetScrapFlavorInfoList(
|
|
ScrapRef scrap,
|
|
UInt32 * infoCount,
|
|
ScrapFlavorInfo info[]);
|
|
|
|
|
|
|
|
/*
|
|
CallInScrapPromises forces all promises to be kept.
|
|
If your application promises at least one flavor
|
|
AND it does NOT adopt the new event model, you
|
|
should call this function when your application
|
|
is about to quit. If your app promises no flavors,
|
|
there is no need to call this function, and if
|
|
your app adopts the new event model, this function
|
|
will be called automagically for you. It doesn't
|
|
hurt to call this function more than once, though
|
|
promise keepers may be asked to keep promises
|
|
they already tried and failed.
|
|
*/
|
|
|
|
/*
|
|
* CallInScrapPromises()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: in CarbonLib 1.0 and later
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API( OSStatus )
|
|
CallInScrapPromises(void);
|
|
|
|
|
|
|
|
#if PRAGMA_STRUCT_ALIGN
|
|
#pragma options align=reset
|
|
#elif PRAGMA_STRUCT_PACKPUSH
|
|
#pragma pack(pop)
|
|
#elif PRAGMA_STRUCT_PACK
|
|
#pragma pack()
|
|
#endif
|
|
|
|
#ifdef PRAGMA_IMPORT_OFF
|
|
#pragma import off
|
|
#elif PRAGMA_IMPORT
|
|
#pragma import reset
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* __SCRAP__ */
|
|
|