Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

New Data Handler APIs

QuickTime 5 includes the addition of new data handler APIs –– DataHGetFileTypeOrdering and DataHGetMIMETypeAsync, discussed in this section.

The DataHGetFileTypeOrdering call allows for returning a list defining the order that file type-related information should be considered (for example, file type, file extension, MIME type) by a client. This allows a data handler such the URL data handler to indicate that MIME type information is more useful than, say, filename extension or Mac OS file type.

The DataHGetMIMETypeAsync call has been introduced in order to remove synchronous blocks from QuickTime’s movie opening code.

QuickTime 5 also introduces a Pointer data handler, which supports references to data in memory.

DataHGetFileTypeOrdering

Returns a handle of OSTypes which defines a preferred ordering for file typing information.

ComponentResult DataHGetFileTypeOrdering(DataHandler dh,
DataHFileTypeOrderingHandle * orderingListHandle);

Parameters

dh

the data handler

orderlingListHandle

The OSTypes in the list can have one of these values:

// Types for DataHGetFileTypeOrdering

enum {

kDataHFileTypeMacOSFileType= 'ftyp',

kDataHFileTypeExtension= 'fext',

kDataHFileTypeMIME= 'mime'

};

Discussion

This is a new optional data handler component API that allows for returning a handle of OSTypes. The returned handle may only contain a subset of the currently defined types (i.e., Mac OS file type, extension, MIME type) to limit the consideration to reasonable types. For example, a Mac OS file type isn’t meaningful if a data handler doesn’t know it.

Before making a call to DataHGetFileTypeOrdering, the client should have opened the data handler and called DataHSetDataRef or DataHSetDataRefWithAnchor. This allows the data handler to return a different ordering based on the particular file. This might allow for a data handler to vary its ordering based on the location of the file. For example, on the Mac OS, it might use extensions only on foreign volumes. For other volumes, it might use a Mac OS file type followed by a file extension.

If the data handler has not set the data reference, it can either choose to return an error, or a reasonable default ordering list.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

GetMovieImporterForDataRef (Updated)

The GetMovieImporterForDataRef function has been updated to call DataHGetMIMETypeAsync if instructed to do so. There is a new flag kGetMovieImporterUseAsyncCalls that the client can pass to indicate this behavior. If GetMovieImporterForDataRef is allowed to use async calls, it should return notEnoughDataErr if it would block. Without this flag, the call may block.

DataHGetMIMETypeAsync

Accommodates asynchronous discovery of a HTTP/FTP connection’s MIME type.

pascal ComponentResult DataHGetMIMETypeAsync(DataHandler dh, Str255
   mimeType, DataHCompletionUPP
   completionRtn, long refCon);

Discussion

The DataHGetMIMETypeAsync call removes synchronous blocks from QuickTime’s movie opening code. DataHGetMIMEType, the only call available before, will block if the data is not available yet and will continue blocking until either the information becomes available or the operation times out in 60 seconds. If it times out, it returns the error notEnoughDataErr.

The semantics of usage are the same as the already-available DataHGetFileTypeAsync call. With each call, a pointer to the value to be updated is passed to the routine. For DataHGetMIMEType, it is a pointer to a Str255 that will hold the MIME type when (if) it becomes available. The completionRtn is a standard DataHCompletion proc that is called when either the data becomes available or there is a failure (timeout, DataHFinishData() called with cancel). The refCon value is passed to the completion routine. The pointer will not be updated until the completion routine fires.

If a completion routine is not specified, however, the call will return immediately. If the MIME type is known, it will update mimeType and return noErr. If the information is not known yet, the error notEnoughDataErr will be returned. This allows non-blocking calls to be made to DataHGetMIMETypeAsync. If it returns another error, that indicates some other failure.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

QTGetMIMETypeInfo

Allows information to be retrieved about a particular MIME type. The type of information is specified by a selector.

pascal OSErr QTGetMIMETypeInfo ( const char * mimeStringStart, short
   mimeStringLength, OSType infoSelector,
   void *infoDataPtr, long *infoDataSize );

Parameters

mimeStringStart

pointer to the first character of a string holding the MIME type.

mimeStringLength

number of characters in the MIME type string. (With mimeStringStart, this allows references to Pascal, C, and non-delimited string buffers to be passed with euqal abandon.)

infoSelector

type of information being requested. Two selectors are defined:

kQTGetMIMETypeInfoIsQuickTimeMovieType = 'moov'

Corresponds to a MIME type for a QuickTime movie. The current check is against "video/quicktime" and "application/x-quicktimeplayer" but can be extended in the future. The info is a pointer to a Boolean.

kQTGetMIMETypeInfoIsQuickTimeMovieType

Useful in trying to determine an importer, this returns false for "application/octet-stream", a MIME type which often indicates a poorly configured server. This allows the MIME check to be bypassed for obviously bogus MIME type information. The info is a pointer to a Boolean.

infoDataPtr

pointer to the value to be updated.

infoDataSize

on input, the size of the data being expected; on output, the siaze of the data being retrieved. (In all current cases these will hold the same size. In general, this approach allows some sanity checking on the size of the info data buffer passed.)

Availability

• Available in Mac OS X v10.0 and later.

Declared In

In this section:

Pointer Data Handler
New Load State Defined
Autoplay and the Movie Toolbox
New Media Type Supported

Pointer Data Handler

The Pointer data handler adds to the complement of other QuickTime data handlers. Like the Handle Data Handler, the Pointer data handler supports references to data in memory; unlike the Handle data handler, the Pointer data handler does not require that data reside within a block allocated by the Macintosh Memory Manager. You just specify the memory address of the data and its length, and the Pointer data handler will do the rest.

The Pointer data handler allows you to submit data for use by QuickTime via direct memory address. However, it does not eliminate the use of handles in QuickTime’s data handler API. Data references themselves are still stored in handles on which QuickTime will call GetHandleSize. The API also requires that ancillary pieces of information about data references, such as their names and MIME types, are passed to QuickTime in handle blocks, not pointer blocks.

A pointer data ref record has the following definition:

struct PointerDataRefRecord {

    void        *data;

    Size        dataLength;

};

typedef PointerDataRefRecord *PointerDataRefPtr;

typedef PointerDataRefPtr *PointerDataRef;

The code snippet in Listing 1-8 shows you how you can open media at a specific memory address as a QuickTime movie. The snippet does not include error checking.

Listing 1-8  Opening media at a specific memory address as a QuickTime movie

     Str255 mimeTypePascalStr;

     Str255 namePascalStr;

     Handle dataRefXtnsnHndl;

     ComponentInstance dataHandler;

     PointerDataRef dataref =

                (PointerDataRef)NewHandle(sizeof(PointerDataRefRecord));

     (**dataref).data = myPointerToSomeMedia;

     (**dataref).dataLength = theLengthOfTheMedia;

     osstat = OpenADataHandler(dataRef, PointerDataHandlerSubType, nil,

                            (OSType)0, nil, kDataHCanRead, &dataHandler);

     // mix in the the mime type of the media

     osstat = PtrToHand(mimeTypePascalStr, &dataRefXtnsnHndl,

                        mimeTypePascalStr[0]+1);

     osstat = DataHSetDataRefExtension(dataHandler, dataRefXtnsnHndl,

                                        kDataRefExtensionMIMEType);

     DisposeHandle(dataRefXtnsnHndl);

     // mix in the name of the media

     osstat = PtrToHand(namePascalStr, &dataRefXtnsnHndl, namePascalStr

                        [0]+1);

     osstat = DataHSetDataRefExtension(dataHandler, dataRefXtnsnHndl,

                                        kDataRefExtensionFileName);

     DisposeHandle(dataRefXtnsnHndl);

     // don't need our data handler instance anymore

     CloseComponent(dataHandler);

     // make a movie

     osstat = NewMovieFromDataRef(&newMovie, newMovieActive +

                                    newMovieIdleImportOK +

                                    newMovieAsyncOK, &newResID, dataref,

                                    PointerDataHandlerSubType);

New Load State Defined

QuickTime 5 introduces a new load state, defined for the call GetMovieLoadState, between kMovieLoadStatePlayable and kMovieLoadStateComplete called kMovieLoadStatePlaythroughOK. This value will be returned after the movie has become playable, as soon as QuickTime calculates that the download would complete before the playback would complete. As previously, when a download completes, GetMovieLoadState returns kMovieLoadStateComplete.

Autoplay and the Movie Toolbox

mcActionAutoPlay is a new movie controller action introduced in QuickTime 5 that enables you to start a QuickTime movie playing automatically as soon as there is a sufficient amount of data available to play it to completion. This mirrors behavior previously available only in the QuickTime Plugin.

mcActionAutoPlay enables support for a feature such as QuickTime Player’s autoplay, which allows you to automatically begin playback of a movie as soon as it is appropriate. If it is a movie that is being transferred via HTTP, for example, it won’t start to play until QuickTime calculates that the download would complete before the playback would complete.

New Media Type Supported

A new media type is introduced in QuickTime 5. The GSM Importer, a new movie importer defined by the file extension .gsm, the file type 'GSM ', and the MIME type audio/x-gsm, is used to handle new media configurations specified by the QuickTime Plugin and the control panel in QuickTime 5.

Encoding GSM Audio

QuickTime does not encode GSM audio, so you have to use another tool if you want to create *.gsm files. MacGSM is a useful tool and available at <http://w3com.com/m2com/#MacGSM>. When using MacGSM to encode, you start with a *.au file that is encoded at 16 bits - 8 kHz - mono with 2:1 uLaw compression. The 8 kHz mono setting in the QuickTime movie export dialog for Sound to uLaw exports correctly for this purpose. Then, you drop your *.au file onto MacGSM while holding down the option key. MacGSM will create a *.au.gsm file that you can then open with QuickTime via the new GSM movie importer.

< Previous PageNext 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.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice