Data Components Reference for QuickTime

Framework
Frameworks/QuickTime.framework
Declared in
Files.h
QuickTimeComponents.h

Overview

Data components allow applications to place various types of data into a QuickTime movie or extract data from a movie in a specified format.

Functions by Task

Data Codec Functions

Identifying Data References

Managing Data Handler Components

Reading Movie Data

Selecting a Data Handler

Using Data References to Access Media

Working With The Idle Manager

Writing Movie Data

Supporting Functions

Functions

Callbacks

DataHCompletionProc

Called upon completion of a read or write operation.

typedef void (*DataHCompletionProcPtr) (Ptr request, long refcon, OSErr err);

If you name your function MyDataHCompletionProc, you would declare it this way:

void MyDataHCompletionProc (
   Ptr      request,
   long     refcon,
   OSErr    err );

Parameters
request

Specifies a pointer to the data that was associated with the read request DataHScheduleData or write request DataHWrite. The client program uses this pointer to determine which request has completed.

refcon

A reference constant that the client program supplied to your data handler component when it made the original request.

err

Indicates the success or failure of the operation. If the operation succeeded, set this parameter to 0. Otherwise, specify an appropriate error code.

Discussion

Data handler completion functions are guaranteed to be called at non-interrupt time. This means that you can safely call functions that are not interrupt-safe, such as DataHScheduleData, from within a completion function.

Declared In
QuickTimeComponents.h

Data Types

ConstFSSpecPtr

Represents a type used by the Data Components API.

typedef const FSSpec * ConstFSSpecPtr;
Availability
  • Available in OS X v10.0 and later.
Declared In
Files.h

DataCodecComponent

Represents a type used by the Data Components API.

typedef ComponentInstance DataCodecComponent;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
QuickTimeComponents.h

DataHCompletionUPP

Represents a type used by the Data Components API.

typedef STACK_UPP_TYPE(DataHCompletionProcPtr) DataHCompletionUPP;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
QuickTimeComponents.h

DataHFileTypeOrderingHandle

Represents a type used by the Data Components API.

typedef DataHFileTypeOrderingPtr * DataHFileTypeOrderingHandle;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
QuickTimeComponents.h

DataHFileTypeOrderingPtr

Represents a type used by the Data Components API.

typedef OSType * DataHFileTypeOrderingPtr;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
QuickTimeComponents.h

DataHSchedulePtr

Represents a type used by the Data Components API.

typedef DataHScheduleRecord * DataHSchedulePtr;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
QuickTimeComponents.h

DataHScheduleRecord

Provides scheduling information for scheduled reads.

struct DataHScheduleRecord {
   TimeRecord    timeNeededBy;
   long          extendedID;
   long          extendedVers;
   Fixed         priority;
};
Fields
timeNeededBy
Discussion

Specifies the time at which your data handler must deliver the requested data to the calling program. This time value is relative to the time base that is contained in this time record. During pre-roll operations, the Movie Toolbox may use special values in certain time record fields. The time record fields in question are the scale and value fields. By correctly interpreting the values of these fields, your data handler can queue up the pre-roll read requests in the most efficient way for its device.

extendedID
Discussion

A constant (see below) that indicates the type of data that follows in the remainder of the structure. See these constants:

  • kDataHExtendedSchedule

extendedVers
Discussion

Reserved. This field should always be set to 0.

priority
Discussion

Indicates the relative importance of the data request. Client programs assign a value of 100.0 to data requests the must be delivered. Lower values indicate relatively less critical data. If your data handler must accommodate bandwidth limitations when delivering data, your component may use this value as an indication of which requests can be dropped with the least impact on the client program. As an example, consider using priorities in a frame-differenced movie. Key frames might have priority values of 100.0, indicating that they are essential to proper playback. As you move through the frames following a key frame, each successive frame might have a lower priority value. Once you drop a frame, you must drop all successive frames of equal or lower priority until you reach another key frame, because each of these frames would rely on the dropped one for some image data.

Discussion

There are two types of preroll read operations. The first type is a required read; that is, the Movie Toolbox requires that the read operation be satisfied before the movie starts playing. The second type is an optional read. If your data handler can satisfy the read operation as part of the pre-roll operation, it should do so. Otherwise, your data handler may satisfy the request at a specified time while the movie is playing. The Movie Toolbox indicates that a preroll read request is required by setting the scale field of the time record to -1. This literally means that the request is scheduled for a time that is infinitely far into the future. Your data handler should collect all such read requests, order them most efficiently for your device, and process them when the Movie Toolbox calls your component's DataHFinishData function. For optional preroll read requests, the Movie Toolbox sets the scale field properly, but negates the contents of the value field. Your data handler has the option of delivering the data for this request with the required data, if that can be done efficiently. Otherwise, your data handler may deliver the data at its schedule time. You determine the scheduled time by negating the contents of the value field (that is, multiplying by -1).

Declared In
QuickTimeComponents.h

DataHVolumeList

Represents a type used by the Data Components API.

typedef DataHVolumeListPtr * DataHVolumeList;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
QuickTimeComponents.h

DataHVolumeListPtr

Represents a type used by the Data Components API.

typedef DataHVolumeListRecord * DataHVolumeListPtr;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
QuickTimeComponents.h

XMLDoc

Represents a type used by the Data Components API.

typedef XMLDocRecord * XMLDoc;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
QuickTimeComponents.h

XMLDocRecord

Undocumented

struct XMLDocRecord {
   void *        xmlDataStorage;
   XMLElement    rootElement;
};
Fields
xmlDataStorage
Discussion

Undocumented

rootElement
Discussion

Undocumented

Declared In
QuickTimeComponents.h

Constants

kDataHCanRead

Constants grouped with kDataHCanRead.

enum {
   kDataHCanRead                 = 1L << 0,
   kDataHSpecialRead             = 1L << 1,
   kDataHSpecialReadFile         = 1L << 2,
   kDataHCanWrite                = 1L << 3,
   kDataHSpecialWrite            = 1 << 4,
   kDataHSpecialWriteFile        = 1 << 5,
   kDataHCanStreamingWrite       = 1 << 6,
   kDataHMustCheckDataRef        = 1 << 7
};
Constants
kDataHCanRead

Indicates that your data handler can read from the volume.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in QuickTimeComponents.h.

kDataHSpecialRead

Indicates that your data handler can read from the volume using a specialized method. For example, your data handler might support access to networked multimedia servers using a special protocol. In that case, your component would set this flag to 1 whenever the volume resides on a supported server.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in QuickTimeComponents.h.

kDataHSpecialReadFile

Reserved for use by Apple.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in QuickTimeComponents.h.

kDataHCanWrite

Indicates that your data handler can write data to the volume. In particular, use this flag to indicate that your data handler's DataHPutData function will work with this volume.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in QuickTimeComponents.h.

kDataHSpecialWrite

Indicates that your data handler can write to the volume using a specialized method. As with the kDataHSpecialRead flag, your data handler would use this flag to indicate that your component can access the volume using specialized support (for example, special network protocols).

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in QuickTimeComponents.h.

kDataHCanStreamingWrite

Indicates that your data handler can support the special write functions for capturing movie data when writing to this volume.

Available in OS X v10.0 and later.

Not available to 64-bit applications.

Declared in QuickTimeComponents.h.

Declared In
QuickTimeComponents.h

DataHScheduleRecord Values

Constants passed to DataHScheduleRecord.

enum {
   kDataHExtendedSchedule        = 'xtnd'
};
Declared In
QuickTimeComponents.h

DataHGetFileTypeOrdering Values

Constants passed to DataHGetFileTypeOrdering.

enum {
   kDataHFileTypeMacOSFileType   = 'ftyp',
   kDataHFileTypeExtension       = 'fext',
   kDataHFileTypeMIME            = 'mime'
};
Declared In
QuickTimeComponents.h

DataHGetInfoFlags Values

Constants passed to DataHGetInfoFlags.

enum {
   kDataHInfoFlagNeverStreams    = 1 << 0, /* set if this data handler doesn't stream*/
   kDataHInfoFlagCanUpdateDataRefs = 1 << 1, /* set if this data handler might update data reference*/
   kDataHInfoFlagNeedsNetworkBandwidth = 1 << 2 /* set if this data handler may need to occupy the network*/
};
Declared In
QuickTimeComponents.h

DataHSetMovieUsageFlags Values

Constants passed to DataHSetMovieUsageFlags.

enum {
   kDataHMovieUsageDoAppendMDAT  = 1L << 0 /* if set,
   datahandler should append wide and mdat atoms in append call*/
};
Declared In
QuickTimeComponents.h