Next Page >

Hide TOC

CGDataConsumer Reference

Derived from	CFType
Framework	ApplicationServices/ApplicationServices.h
Companion guide	Quartz 2D Programming Guide
Declared in	CGDataConsumer.h

Overview

The CGDataConsumerRef opaque type abstracts the data-writing task and eliminates the need for applications to manage data through a raw memory buffer. You can use data consumer objects to write image or PDF data and all, except for CGDataConsumerCreateWithCFData, are available in Mac OS X v10.0 or later.

If your application runs in Mac OS X v10.4 or later, you should use CGImageDestination objects rather than data consumers. See CGImageDestination Reference.

Functions by Task

Creating Data Consumers

Getting the CFType ID

Retaining and Releasing Data Consumers

Functions

CGDataConsumerCreate

Creates a data consumer that uses callback functions to write data.

CGDataConsumerRef CGDataConsumerCreate (
   void *info,
   const CGDataConsumerCallbacks *callbacks
);

Parameters

info: A pointer to data of any type or NULL. When Quartz calls the functions specified in the callbacks parameter, it passes this pointer as the info parameter.
callbacks: A pointer to a CGDataConsumerCallbacks structure that specifies the callback functions you implement to copy data sent to the consumer and to handle the consumer’s basic memory management. For a complete description, see CGDataConsumerCallbacks.

Return Value

A new data consumer object. You are responsible for releasing this object using CGDataConsumerRelease.

Availability

Available in Mac OS X version 10.0 and later.

Related Sample Code

CarbonSketch

Declared In

CGDataConsumer.h

CGDataConsumerCreateWithCFData

Creates a data consumer that writes to a CFData object.

CGDataConsumerRef CGDataConsumerCreateWithCFData (
   CFMutableDataRef data
);

Parameters

data: The CFData object to write to.

Return Value

A new data consumer object. You are responsible for releasing this object using CGDataConsumerRelease.

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 that you then copy to the pasteboard.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGDataConsumer.h

CGDataConsumerCreateWithURL

Creates a data consumer that writes data to a location specified by a URL.

CGDataConsumerRef CGDataConsumerCreateWithURL (
   CFURLRef url
);

Parameters

url: A CFURL object that specifies the data destination.

Return Value

A new data consumer object. You are responsible for releasing this object using CGDataConsumerRelease.

Availability

Available in Mac OS X version 10.0 and later.

Declared In

CGDataConsumer.h

CGDataConsumerGetTypeID

Returns the Core Foundation type identifier for Quartz data consumers.

CFTypeID CGDataConsumerGetTypeID (
   void
);

Return Value

The Core Foundation identifier for the opaque type CGDataConsumerRef.

Availability

Available in Mac OS X version 10.2 and later.

Declared In

CGDataConsumer.h

CGDataConsumerRelease

Decrements the retain count of a data consumer.

void CGDataConsumerRelease (
   CGDataConsumerRef consumer
);

Parameters

consumer: The data consumer to release.

Discussion

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

Availability

Available in Mac OS X version 10.0 and later.

Related Sample Code

CarbonSketch

Declared In

CGDataConsumer.h

CGDataConsumerRetain

Increments the retain count of a data consumer.

CGDataConsumerRef CGDataConsumerRetain (
   CGDataConsumerRef consumer
);

Parameters

consumer: The data consumer to retain.

Return Value

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

Discussion

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

Availability

Available in Mac OS X version 10.0 and later.

Declared In

CGDataConsumer.h

Callbacks

CGDataConsumerPutBytesCallback

Copies data from a Quartz-supplied buffer into a data consumer.

size_t (*CGDataConsumerPutBytesCallback) (
   void *info,
   const void *buffer,
   size_t count
);

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

size_t MyConsumerPutBytes (
   void *info,
   const void *buffer,
   size_t count
);

Parameters

info: A generic pointer to private data shared among your callback functions. This is the pointer supplied to CGDataConsumerCreate.
buffer: The Quartz-supplied buffer from 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 consumer, you should return 0.

Discussion

When Quartz is ready to send data to the consumer, your function is called. It should copy the specified number of bytes from buffer into some resource under your control—for example, a file.

For information on how to associate your callback function with a data consumer, see CGDataConsumerCreate and CGDataConsumerCallbacks.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGDataConsumer.h

CGDataConsumerReleaseInfoCallback

Releases any private data or resources associated with the data consumer.

void (*CGDataConsumerReleaseInfoCallback) (
   void *info
);

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

void MyConsumerReleaseInfo (
   void *info
);

Parameters

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

Discussion

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

For information on how to associate your callback function with a data consumer, see CGDataConsumerCreate and CGDataConsumerCallbacks.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGDataConsumer.h

Data Types

CGDataConsumerCallbacks

A structure that contains pointers to callback functions that manage the copying of data for a data consumer.

struct CGDataConsumerCallbacks {
   CGDataConsumerPutBytesCallback putBytes;
   CGDataConsumerReleaseInfoCallback releaseConsumer;
};
typedef struct CGDataConsumerCallbacks CGDataConsumerCallbacks;

Fields

putBytes: A pointer to a function that copies data to the data consumer. For more information, see CGDataConsumerPutBytesCallback.
releaseConsumer: A pointer to a function that handles clean-up for the data consumer, or NULL. For more information, see CGDataConsumerReleaseInfoCallback

Discussion

The functions specified by the CGDataConsumerCallbacks structure are responsible for copying data that Quartz sends to your consumer and for handling the consumer’s basic memory management. You supply a CGDataConsumerCallbacks structure to the function CGDataConsumerCreate to create a data consumer.

Availability

Available in Mac OS X v10.0 and later.

Declared In

CGDataConsumer.h