diff options
Diffstat (limited to 'common/quicktime_win32/Scrap.h')
| -rw-r--r-- | common/quicktime_win32/Scrap.h | 691 |
1 files changed, 691 insertions, 0 deletions
diff --git a/common/quicktime_win32/Scrap.h b/common/quicktime_win32/Scrap.h new file mode 100644 index 0000000..cc9ece5 --- /dev/null +++ b/common/quicktime_win32/Scrap.h @@ -0,0 +1,691 @@ +/* + 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__ */ + |