Next Page >

Hide TOC

CGDataProvider Reference

Derived from	CFType Reference
Framework	ApplicationServices/ApplicationServices.h
Declared in	CGDataProvider.h

Overview

The CGDataProvider header file declares a data type that supplies Quartz functions with data. Data provider objects abstract the data-access task and eliminate the need for applications to manage data through a raw memory buffer.

For information on how to use CGDataProvider functions, see Quartz 2D Programming Guide Programming Guide.

Functions

CGDataProviderCopyData

Returns a copy of the provider’s data.

CFDataRef CGDataProviderCopyData(
   CGDataProviderRef provider
);

Parameters

provider: The data provider whose data you want to copy.

Return Value

A new data object containing a copy of the provider’s data. You are responsible for releasing this object.

Availability

Available in Mac OS X v10.5 and later.

Declared In

CGDataProvider.h

CGDataProviderCreateDirect

Creates a Quartz direct-access data provider.

CGDataProviderRef CGDataProviderCreateDirect (
   void *info,
   off_t size,
   const CGDataProviderDirectCallbacks *callbacks
);

Parameters

info: A pointer to data of any type or NULL. When Quartz calls the functions specified in the callbacks parameter, it sends each of the functions this pointer.
size: The number of bytes of data to provide.
callbacks: A pointer to a CGDataProviderDirectCallbacks structure that specifies the callback functions you implement to handle the data provider’s basic memory management.

Return Value

A new data provider. You are responsible for releasing this object using CGDataProviderRelease.

Discussion

You use this function to create a direct-access data provider that uses callback functions to read data from your program in a single block.

Availability

Available in Mac OS X v10.5 and later.

Declared In

CGDataProvider.h

CGDataProviderCreateSequential

Creates a Quartz sequential-access data provider.

CGDataProviderRef CGDataProviderCreateSequential (
   void *info,
   const CGDataProviderSequentialCallbacks *callbacks
);

Parameters

info: A pointer to data of any type or NULL. When Quartz calls the functions specified in the callbacks parameter, it sends each of the functions this pointer.
callbacks: A pointer to a CGDataProviderSequentialCallbacks structure that specifies the callback functions you implement to handle the data provider’s basic memory management.

Return Value

A new data provider. You are responsible for releasing this object using CGDataProviderRelease.

Discussion

You use this function to create a sequential-access data provider that uses callback functions to read data from your program in a single block.

Availability

Available in Mac OS X v10.5 and later.

Declared In

CGDataProvider.h

CGDataProviderCreateWithCFData

Creates a Quartz data provider that reads from a CFData object.

CGDataProviderRef CGDataProviderCreateWithCFData (
   CFDataRef data
);

Parameters

data: The CFData object to read from.

Return Value

A new data provider. You are responsible for releasing this object using CGDataProviderRelease.

Discussion

You can use this function when you need to represent Quartz data as a CFData type. For example, you might create a CFData object when reading data from the pasteboard.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGDataProvider.h

CGDataProviderCreateWithData

Creates a Quartz direct-access data provider that uses data your program supplies.

CGDataProviderRef CGDataProviderCreateWithData (
   void *info,
   const void *data,
   size_t size,
   CGDataProviderReleaseDataCallback releaseData
);

Parameters

info: A pointer to data of any type, or NULL. When Quartz calls the function specified in the releaseData parameter, Quartz sends it this pointer as its first argument.
data: A pointer to the array of data that the provider contains.
size: A value that specifies the number of bytes that the data provider contains.
releaseData: A pointer to a release callback for the data provider, or NULL. Your release function is called when Quartz frees the data provider. For more information, see CGDataProviderReleaseDataCallback.

Return Value

A new data provider. You are responsible for releasing this object using CGDataProviderRelease.

Discussion

You use this function to create a direct-access data provider that uses callback functions to read data from your program an entire block at one time.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

CarbonSketch

Declared In

CGDataProvider.h

CGDataProviderCreateWithFilename

Creates a Quartz direct-access data provider that uses a file to supply data.

CGDataProviderRef CGDataProviderCreateWithFilename(
   const char *filename
);

Parameters

filename: The full or relative pathname to use for the data provider. When you supply Quartz data via the provider, it reads the data from the specified file.

Return Value

A new data provider or NULL if the file could not be opened. You are responsible for releasing this object using CGDataProviderRelease.

Discussion

You use this function to create a direct-access data provider that supplies data from a file. When you supply Quartz with a direct-access data provider, Quartz obtains data from your program in a single block.

Availability

Available in Mac OS X v10.0 and later.

Declared In

CGDataProvider.h

CGDataProviderCreateWithURL

Creates a Quartz direct-access data provider that uses a URL to supply data.

CGDataProviderRef CGDataProviderCreateWithURL (
   CFURLRef url
);

Parameters

url: A CFURL object to use for the data provider. When you supply Quartz data via the provider, it reads the data from the URL address.

Return Value

A new data provider or NULL if the data from the URL could not be accessed. You are responsible for releasing this object using CGDataProviderRelease.

Discussion

You use this function to create a direct-access data provider that supplies data from a URL. When you supply Quartz with a direct-access data provider, Quartz obtains data from your program in a single entire block.

Availability

Available in Mac OS X v10.0 and later.

Declared In

CGDataProvider.h

CGDataProviderGetTypeID

Returns the Core Foundation type identifier for Quartz data providers.

CFTypeID CGDataProviderGetTypeID (
   void
);

Return Value

The identifier for the opaque type CGDataProviderRef.

Availability

Available in Mac OS X v10.2 and later.

Declared In

CGDataProvider.h

CGDataProviderRelease

Decrements the retain count of a data provider.

void CGDataProviderRelease (
   CGDataProviderRef provider
);

Parameters

provider: The data provider to release.

Discussion

This function is equivalent to CFRelease, except that it does not cause an error if the provider parameter is NULL.

Availability

Available in Mac OS X v10.0 and later.

Declared In

CGDataProvider.h

CGDataProviderRetain

Increments the retain count of a data provider.

CGDataProviderRef CGDataProviderRetain (
   CGDataProviderRef provider
);

Parameters

provider: The data provider to retain.

Return Value

The same data provider you passed in as the provider parameter.

Discussion

This function is equivalent to CFRetain, except that it does not cause an error if the provider parameter is NULL.

Availability

Available in Mac OS X v10.0 and later.

Declared In

CGDataProvider.h

Callbacks by Task

Sequential-Access Data Provider Callbacks

Direct-Access Data Provider Callbacks

Callbacks

CGDataProviderGetBytePointerCallback

A callback function that returns a generic pointer to the provider data.

const void * (*CGDataProviderGetBytePointerCallback) (
   void *info
);

If you name your function MyProviderGetBytePointer, you would declare it like this:

void *MyProviderGetBytePointer (
   void *info
);

Parameters

info: A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGDataProviderCreateDirectAccess.

Return Value

A generic pointer to your provider data. By suppling this pointer, you are giving Quartz read-only access to both the pointer and the underlying provider data. You must not move or modify the provider data until Quartz calls your CGDataProviderReleaseBytePointerCallback function.

Discussion

When Quartz needs direct access to your provider data, this function is called.

For information on how to associate your function with a direct-access data provider, see CGDataProviderCreateDirectAccess and CGDataProviderDirectAccessCallbacks.

Availability

Available in Mac OS X v10.3 and later.

Declared In

CGDataProvider.h

CGDataProviderGetBytesAtOffsetCallback

A callback function that copies data from the provider into a Quartz buffer.

typedef size_t (*CGDataProviderGetBytesAtOffsetCallback) (
   void *info,
   void *buffer,
   size_t offset,
   size_t count
);

If you name your function MyProviderGetBytesWithOffset, you would declare it like this:

size_t MyProviderGetBytesWithOffset (
   void *info,
   void *buffer,
   size_t offset,
   size_t count
);

Parameters

info: A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGDataProviderCreateDirectAccess.
buffer: The Quartz-supplied buffer into which you copy the specified number of bytes.
offset: Specifies the relative location in the data provider at which to begin copying data.
count: The number of bytes to copy.

Return Value

The number of bytes copied. If no more data can be written to the buffer, you should return 0.

Discussion

When Quartz is ready to receive data from the provider, your function is called.

For information on how to associate your function with a direct-access data provider, see CGDataProviderCreateDirectAccess and CGDataProviderDirectAccessCallbacks.

Availability

Available in Mac OS X v10.3 and later.

Declared In

CGDataProvider.h

CGDataProviderGetBytesAtPositionCallback

A callback function that copies data from the provider into a Quartz buffer.

typedef size_t (*CGDataProviderGetBytesAtPositionCallback) (
   void *info,
   void *buffer,
   off_t position,
   size_t count
);

If you name your function MyProviderGetBytesAtPosition, you would declare it like this:

size_t MyProviderGetBytesAtPosition (
   void *info,
   void *buffer,
   off_t position,
   size_t count
);

Parameters

info: A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGDataProviderCreateDirect.
buffer: The Quartz-supplied buffer into which you copy the specified number of bytes.
position: Specifies the relative location in the data provider at which to begin copying data.
count: The number of bytes to copy.

Return Value

The number of bytes copied. If no more data can be written to the buffer, you should return 0.

Discussion

When Quartz is ready to receive data from the provider, your function is called.

Availability

Available in Mac OS X v10.5 and later.

Declared In

CGDataProvider.h

CGDataProviderGetBytesCallback

A callback function that copies from a provider data stream into a Quartz-supplied buffer.

size_t (*CGDataProviderGetBytesCallback) (
   void *info,
   void *buffer,
   size_t count
);

If you name your function MyProviderGetBytes, you would declare it like this:

size_t MyProviderGetBytes (
   void *info,
   void *buffer,
   size_t count
);

Parameters

info: A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGDataProviderCreate.
buffer: The Quartz-supplied buffer into which you copy the specified number of bytes.
count: The number of bytes to copy.

Return Value

The number of bytes copied. If no more data can be written to the buffer, you should return 0.

Discussion

When Quartz is ready to receive data from the provider data stream, your function is called. It should copy the specified number of bytes into buffer.

For information on how to associate your callback function with a data provider, see CGDataProviderCreate and CGDataProviderCallbacks.

Availability

Available in Mac OS X v10.3 and later.

Declared In

CGDataProvider.h

CGDataProviderReleaseBytePointerCallback

A callback function that releases the pointer Quartz obtained by calling CGDataProviderGetBytePointerCallback.

typedef void (*CGDataProviderReleaseBytePointerCallback) (
   void *info,
   const void *pointer
);

If you name your function MyProviderReleaseBytePointer, you would declare it like this:

void MyProviderReleaseBytePointer (
   void *info,
   const void *pointer
);

Parameters

info: A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGDataProviderCreateDirectAccess.
pointer: A pointer to your provider data. This is the same pointer you returned in CGDataProviderGetBytePointerCallback.

Discussion

When Quartz no longer needs direct access to your provider data, your function is called. You may safely modify, move, or release your provider data at this time.

For information on how to associate your function with a direct-access data provider, see CGDataProviderCreateDirectAccess and CGDataProviderDirectAccessCallbacks.

Availability

Available in Mac OS X v10.3 and later.

Declared In

CGDataProvider.h

CGDataProviderReleaseDataCallback

A callback function that releases data you supply to the function CGDataProviderCreateWithData.

typedef void (*CGDataProviderReleaseDataCallback) (
   void *info,
   const void *data
   size_t size
);

If you name your function MyProviderReleaseData, you would declare it like this:

void MyProviderReleaseData (
   void *info,
   const void *data
   size_t size
);

Parameters

info: A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGDataProviderCreateWithData.
data: A pointer to your provider data.
size: The size of the data.

Discussion

When Quartz no longer needs direct access to your provider data, your function is called. You may safely modify, move, or release your provider data at this time.

Availability

Available in Mac OS X v10.5 and later.

Declared In

CGDataProvider.h

CGDataProviderReleaseInfoCallback

A callback function that releases any private data or resources associated with the data provider.

void (*CGDataProviderReleaseInfoCallback) (
   void *info
);

If you name your function MyProviderReleaseInfo, you would declare it like this:

void MyProviderReleaseInfo (
   void *info
);

Parameters

info: A generic pointer to private information shared among your callback functions. This is the same pointer you supplied to CGDataProviderCreate.

Discussion

When Quartz frees a data provider that has an associated release function, the release function is called.

For information on how to associate your callback function with a data provider, see CGDataProviderCreate and CGDataProviderCallbacks.

Availability

Available in Mac OS X v10.3 and later.

Declared In

CGDataProvider.h

CGDataProviderRewindCallback

A callback function that moves the current position in the data stream back to the beginning.

void (*CGDataProviderRewindCallback) (
   void *info
);

If you name your function MyProviderRewind, you would declare it like this:

void MyProviderRewind (
   void *info
);

Parameters

info: A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGDataProviderCreate.

Discussion

When Quartz needs to read from the beginning of the provider’s data stream, your function is called.

For information on how to associate your callback function with a data provider, see CGDataProviderCreate and CGDataProviderCallbacks.

Availability

Available in Mac OS X v10.3 and later.

Declared In

CGDataProvider.h

CGDataProviderSkipBytesCallback

A callback function that advances the current position in the data stream supplied by the provider.

void (*CGDataProviderSkipBytesCallback) (
   void *info,
   size_t count
);

If you name your function MyProviderSkipBytes, you would declare it like this:

void MyProviderSkipBytes (
   void *info,
   size_t count
);

Parameters

info: A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGDataProviderCreate.
count: The number of bytes to skip.

Discussion

When Quartz needs to advance forward in the provider’s data stream, your function is called.

For information on how to associate your callback function with a data provider, see CGDataProviderCreate and CGDataProviderCallbacks.

Availability

Available in Mac OS X v10.3 and later.

Declared In

CGDataProvider.h

CGDataProviderSkipForwardCallback

A callback function that advances the current position in the data stream supplied by the provider.

off_t (*CGDataProviderSkipForwardCallback) (
   void *info,
   off_t count
);

If you name your function MyProviderSkipForwardBytes, you would declare it like this:

off_t MyProviderSkipForwardBytes (
   void *info,
   off_t count
);

Parameters

info: A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGDataProviderCreate.
count: The number of bytes to skip.

Return Value

The number of bytes that were actually skipped.

Discussion

When Quartz needs to advance forward in the provider’s data stream, your function is called.

Availability

Available in Mac OS X v10.5 and later.

Declared In

CGDataProvider.h

Data Types

CGDataProviderRef

Defines an opaque type that supplies Quartz with data.

typedef struct CGDataProvider *CGDataProviderRef;

Discussion

Some Quartz routines supply blocks of data to your program. Rather than reading through a raw memory buffer, data provider objects of type CGDataProviderRef allow you to supply Quartz functions with data.

In Mac OS X version 10.2 and later, CGDataProviderRef is derived from CFTypeRef and inherits the properties that all Core Foundation types have in common. For more information, see CFType Reference.

Availability

Available in Mac OS X v10.0 and later.

Declared In

CGDataProvider.h

CGDataProviderCallbacks

Defines a structure containing pointers to client-defined callback functions that manage the sending of data for a sequential-access data provider.

struct CGDataProviderCallbacks {
   CGDataProviderGetBytesCallback getBytes;
   CGDataProviderSkipBytesCallback skipBytes;
   CGDataProviderRewindCallback rewind;
   CGDataProviderReleaseInfoCallback releaseProvider;
};
typedef struct CGDataProviderCallbacks CGDataProviderCallbacks;

Fields

getBytes: A pointer to a function that copies data from the provider. For more information, see CGDataProviderGetBytesCallback.
skipBytes: A pointer to a function that Quartz calls to advance the stream of data supplied by the provider. For more information, see CGDataProviderSkipBytesCallback.
rewind: A pointer to a function Quartz calls to return the provider to the beginning of the data stream. For more information, see CGDataProviderRewindCallback.
releaseProvider: A pointer to a function that handles clean-up for the data provider, or NULL. For more information, see CGDataProviderReleaseInfoCallback.

Discussion

The functions specified by the CGDataProviderCallbacks structure are responsible for sequentially copying data to a memory buffer for Quartz to use. The functions are also responsible for handling the data provider’s basic memory management. You supply a CGDataProviderCallbacks structure to the function CGDataProviderCreate to create a sequential-access data provider.

Availability

Available in Mac OS X v10.0 and later.

Declared In

CGDataProvider.h

CGDataProviderDirectAccessCallbacks

Defines pointers to client-defined callback functions that manage the sending of data for a direct-access data provider.

struct CGDataProviderDirectAccessCallbacks {
   CGDataProviderGetBytePointerCallback getBytePointer;
   CGDataProviderReleaseBytePointerCallback releaseBytePointer;
   CGDataProviderGetBytesAtOffsetCallback getBytes;
   CGDataProviderReleaseInfoCallback releaseProvider;
};
typedef struct CGDataProviderDirectAccessCallbacks  CGDataProviderDirectAccessCallbacks;

Fields

getBytePointer: A pointer to a function that returns a pointer to the provider’s data. For more information, see CGDataProviderGetBytePointerCallback.
releaseBytePointer: A pointer to a function that Quartz calls to release a pointer to the provider’s data. For more information, see CGDataProviderReleaseBytePointerCallback.
getBytes: A pointer to a function that copies data from the provider. For more information, see CGDataProviderGetBytesAtOffsetCallback.
releaseProvider: A pointer to a function that handles clean-up for the data provider, or NULL. For more information, see CGDataProviderReleaseInfoCallback.

Discussion

You supply a CGDataProviderDirectAccessCallbacks structure to the function CGDataProviderCreateDirectAccess to create a data provider for direct access. The functions specified by the CGDataProviderDirectAccessCallbacks structure are responsible for copying data a block at a time to a memory buffer for Quartz to use. The functions are also responsible for handling the data provider’s basic memory management. For the callback to work, one of the getBytePointer and getBytes parameters must be non-NULL. If both are non-NULL, then getBytePointer is used to access the data.

Availability

Available in Mac OS X v10.0 and later.

Declared In

CGDataProvider.h

CGDataProviderDirectCallbacks

Defines pointers to client-defined callback functions that manage the sending of data for a direct-access data provider.

struct CGDataProviderDirectCallbacks {
   unsigned int version;
   CGDataProviderGetBytePointerCallback getBytePointer;
   CGDataProviderReleaseBytePointerCallback releaseBytePointer;
   CGDataProviderGetBytesAtPositionCallback getBytesAtPosition;
   CGDataProviderReleaseInfoCallback releaseInfo;
};
typedef struct CGDataProviderDirectCallbacks  CGDataProviderDirectCallbacks;

Fields

version: The version of this structure. It should be set to 0.
getBytePointer: A pointer to a function that returns a pointer to the provider’s data. For more information, see CGDataProviderGetBytePointerCallback.
releaseBytePointer: A pointer to a function that Quartz calls to release a pointer to the provider’s data. For more information, see CGDataProviderReleaseBytePointerCallback.
getBytesAtPosition: A pointer to a function that copies data from the provider.
releaseInfo: A pointer to a function that handles clean-up for the data provider, or NULL. For more information, see CGDataProviderReleaseInfoCallback.

Discussion

You supply a CGDataProviderDirectCallbacks structure to the function CGDataProviderCreateDirect to create a data provider for direct access. The functions specified by the CGDataProviderDirectCallbacks structure are responsible for copying data a block at a time to a memory buffer for Quartz to use. The functions are also responsible for handling the data provider’s basic memory management. For the callback to work, one of the getBytePointer and getBytesAtPosition parameters must be non-NULL. If both are non-NULL, then getBytePointer is used to access the data.

Availability

Available in Mac OS X v10.5 and later.

Declared In

CGDataProvider.h

CGDataProviderSequentialCallbacks

Defines a structure containing pointers to client-defined callback functions that manage the sending of data for a sequential-access data provider.

struct CGDataProviderSequentialCallbacks {
   unsigned int version;
   CGDataProviderGetBytesCallback getBytes;
   CGDataProviderSkipForwardCallback skipForward;
   CGDataProviderRewindCallback rewind;
   CGDataProviderReleaseInfoCallback releaseInfo;
};
typedef struct CGDataProviderSequentialCallbacks CGDataProviderSequentialCallbacks;

Fields

version: The version of this structure. It should be set to 0.
getBytes: A pointer to a function that copies data from the provider. For more information, see CGDataProviderGetBytesCallback.
skipForward: A pointer to a function that Quartz calls to advance the stream of data supplied by the provider.
rewind: A pointer to a function Quartz calls to return the provider to the beginning of the data stream. For more information, see CGDataProviderRewindCallback.
releaseInfo: A pointer to a function that handles clean-up for the data provider, or NULL. For more information, see CGDataProviderReleaseInfoCallback.

Discussion

The functions specified by the CGDataProviderSequentialCallbacks structure are responsible for sequentially copying data to a memory buffer for Quartz to use. The functions are also responsible for handling the data provider’s basic memory management. You supply a CGDataProviderCallbacks structure to the function CGDataProviderCreateSequential to create a sequential-access data provider.

Availability

Available in Mac OS X v10.5 and later.

Declared In

CGDataProvider.h

Next Page >

Hide TOC

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.