ADC Home > Reference Library > Reference > Carbon > Interapplication Communication > Scrap Manager Reference (Not Recommended) >

< Previous PageNext Page > Hide TOC

Legacy Documentclose button

Important: The Scrap Manager is deprecated in Mac OS X version 10.5 and later. The replacement API is the Pasteboard Manager. For more information, see Pasteboard Manager Programming Guide.

Deprecated Scrap Manager Reference (Not Recommended) Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.5

CallInScrapPromises

Forces all promised flavors to be supplied. (Deprecated in Mac OS X v10.5. Use PasteboardResolvePromises instead.)

OSStatus CallInScrapPromises (
   void
);

Return Value

A result code. See “Scrap Manager Result Codes.”

Discussion

Before quitting, your application should call CallInScrapPromises in order to ensure the user's ability to paste into other applications. Your application should call CallInScrapPromises even if your application does not explicitly promise any flavors.

It doesn't hurt to call CallInScrapPromises more than once, though promise-keeper functions may be asked to keep promises they already tried and failed.

Availability
Declared In
Scrap.h

ClearCurrentScrap

Clears the current scrap. (Deprecated in Mac OS X v10.5. Use PasteboardClear instead.)

OSStatus ClearCurrentScrap (
   void
);

Return Value

A result code. See “Scrap Manager Result Codes.”

Discussion

Call ClearCurrentScrap immediately 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. 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 scrap reference to pass to other functions.

Availability
Declared In
Scrap.h

ClearScrap

Clears a given scrap. (Deprecated in Mac OS X v10.5. Use PasteboardClear instead.)

OSStatus ClearScrap (
   ScrapRef *inOutScrap
);

Parameters
inOutScrap

A pointer to a scrap reference. On input, this parameter should refer to the scrap to clear. On output, ClearScrap returns a reference to the cleared scrap.

Return Value

A result code. See “Scrap Manager Result Codes.”

Discussion

ClearScrap will clear the scrap passed in and return the incremented ScrapRef value. ClearScrap behaves similarly to the GetScrapByName function when called with the kScrapClearNamedScrap option, with the benefit of not requiring a name in the event one is not available.

Availability
Declared In
Scrap.h

DisposeScrapPromiseKeeperUPP

Disposes of a universal procedure pointer to a function that provides promised scrap data. (Deprecated in Mac OS X v10.5.)

void DisposeScrapPromiseKeeperUPP (
   ScrapPromiseKeeperUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Discussion

See ScrapPromiseKeeperProcPtr for more information on promise keeper functions.

Availability
Declared In
Scrap.h

GetCurrentScrap

Obtains a reference to the current scrap. (Deprecated in Mac OS X v10.5. Use PasteboardCreate instead.)

OSStatus GetCurrentScrap (
   ScrapRef *scrap
);

Parameters
scrap

A pointer to a scrap reference. On return, this scrap reference refers to the current scrap.

Return Value

A result code. See “Scrap Manager Result Codes.”

Discussion

Your application can determine if the scrap contents have changed by storing the scrap reference returned by GetCurrentScrap and comparing it against the scrap reference returned by GetCurrentScrap at a later time. If the two scrap references are different, the scrap has changed.

Carbon applications should use GetCurrentScrap instead of checking the convertClipboardFlag in the EventRecord.

The ScrapRef obtained via GetCurrentScrap becomes invalid and unusable after the scrap is cleared. That is, the scrap reference is valid until a Carbon client calls ClearCurrentScrap, a Classic client calls ZeroScrap , or a Cocoa client calls declareTypes:owner:.

Availability
Declared In
Scrap.h

GetScrapByName

Obtains a reference to a named scrap. (Deprecated in Mac OS X v10.5. Use PasteboardCreate instead.)

OSStatus GetScrapByName (
   CFStringRef name,
   OptionBits options,
   ScrapRef *scrap
);

Parameters
name

A CFString containing the name of the scrap to obtain. You may specify a standard scrap by passing one of the constants described in “Named Scraps” in this parameter.

options

A value indicating whether the specified scrap should be cleared after the reference is returned. See “Options for the GetScrapByName Function” for more information.

scrap

A pointer to a scrap reference. On return, this scrap reference refers to the scrap named in the name parameter.

Return Value

A result code. See “Scrap Manager Result Codes.”

Discussion

GetScrapByName allows access to an indefinite number of public or private scraps. The constant kScrapClipboardScrap refers to the "current" scrap. kScrapFindScrap allows Carbon applications 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 applications. Apple recommends using the Java naming convention for your scraps, for example, com.mycompany.scrap.secret.

Availability
Declared In
Scrap.h

GetScrapFlavorCount

Obtains a scrap flavor count to use with the GetScrapFlavorInfoList function. (Deprecated in Mac OS X v10.5. Use PasteboardCopyItemFlavors instead.)

OSStatus GetScrapFlavorCount (
   ScrapRef scrap,
   UInt32 *infoCount
);

Parameters
scrap

A reference to the scrap to get the flavor count for.

infoCount

A pointer to a count variable. On return, specifies the flavor count for the specified scrap.

Return Value

A result code. See “Scrap Manager Result Codes.”

Discussion

For related information, see GetScrapFlavorInfoList.

Availability
Declared In
Scrap.h

GetScrapFlavorData

Obtains the data for the specified flavor from the specified scrap. (Deprecated in Mac OS X v10.5. Use PasteboardCopyItemFlavorData instead.)

OSStatus GetScrapFlavorData (
   ScrapRef scrap,
   ScrapFlavorType flavorType,
   Size *byteCount,
   void *destination
);

Parameters
scrap

A reference to the scrap to get data from.

flavorType

The flavor type to obtain data for. Some flavor types are described in “Scrap Flavor Types.”

byteCount

A pointer to a size variable. Before calling GetScrapFlavorData, specify the maximum number of bytes your buffer can contain. On return, GetScrapFlavorData provides the number of bytes of data that were actually available, even if this is more than you requested.

destination

A pointer to a buffer, local variable, or other storage location created and disposed of by your application. The size, in bytes, must be at least as large as the value you pass in the byteCount parameter. On return, this buffer contains the specified flavor data. The amount of data returned will not exceed the value you passed in byteCount, even if the number of bytes of available data is more than you specified in byteCount.

Return Value

A result code. See “Scrap Manager Result Codes.”

Discussion

This function blocks until the specified flavor data is available.

Availability
Declared In
Scrap.h

GetScrapFlavorFlags

Obtains information about a specified scrap flavor. (Deprecated in Mac OS X v10.5. Use PasteboardGetItemFlavorFlags instead.)

OSStatus GetScrapFlavorFlags (
   ScrapRef scrap,
   ScrapFlavorType flavorType,
   ScrapFlavorFlags *flavorFlags
);

Parameters
scrap

A reference to the scrap to check.

flavorType

The flavor type to check for. Some scrap flavor types are described in “Scrap Flavor Types.”

flavorFlags

A pointer to a variable of type ScrapFlavorFlags; values for this type are described in “Scrap Flavor Flags.” On return, this variable contains information about the flavor specified by the flavorType parameter.

Return Value

A result code. See “Scrap Manager Result Codes.”

Discussion

The GetScrapFlavorFlags function tells you whether the scrap contains data for a particular flavor and, if it does, provides some information about that flavor. This function never blocks, and is useful for deciding whether to enable the Paste item in your Edit menu, among other things.

Availability
Declared In
Scrap.h

GetScrapFlavorInfoList

Fills an array with items which each describe a corresponding flavor in the scrap. (Deprecated in Mac OS X v10.5. Use PasteboardCopyItemFlavors instead.)

OSStatus GetScrapFlavorInfoList (
   ScrapRef scrap,
   UInt32 *infoCount,
   ScrapFlavorInfo info[]
);

Parameters
scrap

A reference to the scrap to get the flavor information for.

infoCount

A pointer to a count variable. Before calling GetScrapFlavorInfoList, set the value to the number of flavors to get information for. Your application typically obtains the flavor count by calling GetScrapFlavorCount.

On return, specifies the number of flavors for which information was supplied, which may be smaller than the number requested.

info

An array of type ScrapFlavorInfo, whose size is indicated by the infoCount parameter. The array is created and disposed of by your application. On return, the array elements contain the flavor information.

Return Value

A result code. See “Scrap Manager Result Codes.”

Availability
Declared In
Scrap.h

GetScrapFlavorSize

Obtains the size of the data for a specified flavor from a scrap. (Deprecated in Mac OS X v10.5. Use PasteboardCopyItemFlavorData instead.)

OSStatus GetScrapFlavorSize (
   ScrapRef scrap,
   ScrapFlavorType flavorType,
   Size *byteCount
);

Parameters
scrap

A reference to the scrap to get the flavor data size from.

flavorType

The flavor type to obtain the size for. Some flavor types are described in “Scrap Flavor Types.”

byteCount

A pointer to a size variable. On return, this variable contains the byte count for the data of the specified flavor.

Return Value

A result code. See “Scrap Manager Result Codes.”

Discussion

This function will block until the size of the data is available. This may mean blocking until the data itself is available, since some scrap senders don't know how big a flavor will be until they've made the flavor data. GetScrapFlavorSize is intended as a prelude to allocating memory and calling GetScrapFlavorData.

Availability
Declared In
Scrap.h

InvokeScrapPromiseKeeperUPP

Calls a universal procedure pointer to a function that provides promised scrap data. (Deprecated in Mac OS X v10.5.)

OSStatus InvokeScrapPromiseKeeperUPP (
   ScrapRef scrap,
   ScrapFlavorType flavorType,
   void *userData,
   ScrapPromiseKeeperUPP userUPP
);

Return Value

A result code. See “Scrap Manager Result Codes.”

Discussion

You should not need to use the function InvokeScrapPromiseKeeperUPP, as the system calls your scrap promise keeper function for you.

Availability
Declared In
Scrap.h

LoadScrap

Reads the scrap from the scrap file into memory. (Deprecated in Mac OS X v10.5.)

OSStatus LoadScrap (
   void
);

Return Value

A result code. See “Scrap Manager Result Codes.”

Discussion

The function allocates memory in your application’s heap to hold the scrap before reading the scrap into memory. The scrap file is located in the System Folder of the startup volume and has the filename as indicated by the scrapName field of the scrap information structure (usually "Clipboard"). If the scrap is already in memory, this function does nothing.

Special Considerations

In Mac OS X, this function does nothing and is no longer necessary.

Availability
Declared In
Scrap.h

NewScrapPromiseKeeperUPP

Creates a new universal procedure pointer to a function that provides promised scrap data. (Deprecated in Mac OS X v10.5.)

ScrapPromiseKeeperUPP NewScrapPromiseKeeperUPP (
   ScrapPromiseKeeperProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your scrap promise keeper function.

Return Value

A UPP to the scrap promise keeper function. See the description of the ScrapPromiseKeeperUPP data type.

Discussion

See ScrapPromiseKeeperProcPtr for more information on promise keeper functions.

Availability
Declared In
Scrap.h

PutScrapFlavor

Puts data on or promises data to the specified scrap. (Deprecated in Mac OS X v10.5. Use PasteboardPutItemFlavor instead.)

OSStatus PutScrapFlavor (
   ScrapRef scrap,
   ScrapFlavorType flavorType,
   ScrapFlavorFlags flavorFlags,
   Size flavorSize,
   const void *flavorData
);

Parameters
scrap

A reference to the scrap to supply data or promises to.

flavorType

The flavor type to supply or promise the data for. Some flavor types are described in “Scrap Flavor Types.”

flavorFlags

A variable of type ScrapFlavorFlags that you use to supply information about the flavor specified by the flavorType parameter. See “Scrap Flavor Flags” for a description of the values you can use in this parameter.

flavorSize

The size of the data you are supplying or promising, in bytes. If you don't know the size, pass kScrapFlavorSizeUnknown to place a promise for data of undetermined size on the scrap. If you pass 0 in this parameter, a flavor with no expected data—not a promise—is placed on the scrap, and the value of the flavorData parameter is ignored.

flavorData

A pointer to a buffer, local variable, or other storage location, created and disposed of by your application. Before calling PutScrapFlavor to put flavor data on the scrap, store the data in this buffer. For information on the number of bytes of data, see the description of the flavorSize parameter.

Pass NULL for this parameter to indicate you will provide data through a subsequent call to PutScrapFlavor, either later in the same code flow or during execution of your ScrapPromiseKeeperProcPtr callback.

The last time you can provide scrap flavor data is when your scrap promise-keeper function gets called. It is not possible to call PutScrapFlavor while handling a suspend event; suspend events under Carbon don't work the way they do under Mac OS 8 and 9.

Return Value

A result code. See “Scrap Manager Result Codes.”

Discussion

PutScrapFlavor is different than PutScrap in that it includes a ScrapRef parameter and it supports promising a flavor for later delivery, rather than supplying it immediately.

Availability
Declared In
Scrap.h

SetScrapPromiseKeeper

Associates an application-defined promise-keeper function with a scrap or removes an associated promise-keeper. (Deprecated in Mac OS X v10.5. Use PasteboardSetPromiseKeeper instead.)

OSStatus SetScrapPromiseKeeper (
   ScrapRef scrap,
   ScrapPromiseKeeperUPP upp,
   const void *userData
);

Parameters
scrap

A reference to the scrap to set the promise-keeper function for.

upp

A universal procedure pointer to a scrap promise-keeper function. For more information, see ScrapPromiseKeeperProcPtr

You can remove a promise-keeper function from a scrap by passing NULL for this parameter.

userData

An untyped pointer to a buffer, local variable, or other storage location, created and disposed of by your application. This value is passed to the promise-keeper function specified by the upp parameter, which can do whatever it needs to do with the value. For example, you might pass a pointer or handle to some private scrap data that your promise-keeper function uses in fabricating one or more promised flavors.

If your promise-keeper function has no need for special user data, pass NULL for this parameter.

Return Value

A result code. See “Scrap Manager Result Codes.”

Availability
Declared In
Scrap.h

UnloadScrap

Writes the scrap from memory to the scrap file. (Deprecated in Mac OS X v10.5.)

OSStatus UnloadScrap (
   void
);

Return Value

A result code. See “Scrap Manager Result Codes.”

Discussion

This function releases the memory occupied by the scrap in your application’s heap. The scrap file is located in the System Folder of the startup volume and has the filename as indicated by the scrapName field of the scrap information structure (usually "Clipboard"). If the scrap is already on the disk, this function does nothing.

Special Considerations

In Mac OS X, this function does nothing and is no longer necessary.

Availability
Declared In
Scrap.h

< Previous PageNext Page > Hide TOC

© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-12-11)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.