1/*
2 * Copyright (c) 2009 Apple Inc. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
11 * file.
12 *
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
20 *
21 * @APPLE_LICENSE_HEADER_END@
22 */
23/*
24     File:       DVComponentGlue/IsochronousDataHandler.h
25
26     Contains:   Component Manager based Isochronous Data Handler
27
28     Copyright:  � 1997-2006 by Apple Computer, Inc., all rights reserved.
29*/
30
31#ifndef __ISOCHRONOUSDATAHANDLER__
32#define __ISOCHRONOUSDATAHANDLER__
33
34#ifndef __CORESERVICES__
35#include <CoreServices/CoreServices.h>
36#endif
37
38#ifndef __MOVIESFORMAT__
39#include <QuickTime/MoviesFormat.h>
40#endif
41
42#ifndef __QUICKTIMECOMPONENTS__
43#include <QuickTime/QuickTimeComponents.h>
44#endif
45
46
47
48
49
50
51
52#if PRAGMA_ONCE
53#pragma once
54#endif
55
56#ifdef __cplusplus
57extern "C" {
58#endif
59
60#if PRAGMA_STRUCT_ALIGN
61    #pragma options align=mac68k
62#elif PRAGMA_STRUCT_PACKPUSH
63    #pragma pack(push, 2)
64#elif PRAGMA_STRUCT_PACK
65    #pragma pack(2)
66#endif
67
68enum {
69  kIDHComponentType             = 'ihlr', /* Component type*/
70  kIDHSubtypeDV                 = 'dv  ', /* Subtype for DV (over FireWire)*/
71  kIDHSubtypeFireWireConference = 'fwc ' /* Subtype for FW Conference*/
72};
73
74
75/* Version of Isochronous Data Handler API*/
76enum {
77  kIDHInterfaceVersion1         = 0x0001 /* Initial relase (Summer '99)*/
78};
79
80
81/* atom types*/
82
83enum {
84  kIDHDeviceListAtomType        = 'dlst',
85  kIDHDeviceAtomType            = 'devc', /* to be defined elsewhere*/
86  kIDHIsochServiceAtomType      = 'isoc',
87  kIDHIsochModeAtomType         = 'mode',
88  kIDHDeviceIDType              = 'dvid',
89  kIDHDefaultIOType             = 'dfio',
90  kIDHIsochVersionAtomType      = 'iver',
91  kIDHUniqueIDType              = 'unid',
92  kIDHNameAtomType              = 'name',
93  kIDHUseCMPAtomType            = 'ucmp',
94  kIDHIsochMediaType            = 'av  ',
95  kIDHDataTypeAtomType          = 'dtyp',
96  kIDHDataSizeAtomType          = 'dsiz', /* ??? packet size vs. buffer size*/
97  kIDHDataBufferSizeAtomType    = 'dbuf', /* ??? packet size vs. buffer size*/
98  kIDHDataIntervalAtomType      = 'intv',
99  kIDHDataIODirectionAtomType   = 'ddir',
100  kIDHSoundMediaAtomType        = 'soun',
101  kIDHSoundTypeAtomType         = 'type',
102  kIDHSoundChannelCountAtomType = 'ccnt',
103  kIDHSoundSampleSizeAtomType   = 'ssiz',
104  kIDHSoundSampleRateAtomType   = 'srat', /* same as video out... (what does this comment mean?)*/
105  kIDHVideoMediaAtomType        = 'vide',
106  kIDHVideoDimensionsAtomType   = 'dimn',
107  kIDHVideoResolutionAtomType   = 'resl',
108  kIDHVideoRefreshRateAtomType  = 'refr',
109  kIDHVideoPixelTypeAtomType    = 'pixl',
110  kIDHVideoDecompressorAtomType = 'deco',
111  kIDHVideoDecompressorTypeAtomType = 'dety',
112  kIDHVideoDecompressorContinuousAtomType = 'cont',
113  kIDHVideoDecompressorComponentAtomType = 'cmpt'
114};
115
116/* I/O Flags */
117enum {
118  kIDHDataTypeIsInput           = 1L << 0,
119  kIDHDataTypeIsOutput          = 1L << 1,
120  kIDHDataTypeIsInputAndOutput  = 1L << 2
121};
122
123
124/* Permission Flags */
125enum {
126  kIDHOpenForReadTransactions   = 1L << 0,
127  kIDHOpenForWriteTransactions  = 1L << 1,
128  kIDHOpenWithExclusiveAccess   = 1L << 2,
129  kIDHOpenWithHeldBuffers       = 1L << 3, /* IDH will hold buffer until ReleaseBuffer()*/
130  kIDHCloseForReadTransactions  = 1L << 4,
131  kIDHCloseForWriteTransactions = 1L << 5
132};
133
134
135/*
136   Errors
137    These REALLY need to be moved into Errors.h
138   ����needs officially assigned numbers
139*/
140enum {
141  kIDHErrDeviceDisconnected     = -14101,
142  kIDHErrInvalidDeviceID        = -14102,
143  kIDHErrDeviceInUse            = -14104,
144  kIDHErrDeviceNotOpened        = -14105,
145  kIDHErrDeviceBusy             = -14106,
146  kIDHErrDeviceReadError        = -14107,
147  kIDHErrDeviceWriteError       = -14108,
148  kIDHErrDeviceNotConfigured    = -14109,
149  kIDHErrDeviceList             = -14110,
150  kIDHErrCompletionPending      = -14111,
151  kIDHErrDeviceTimeout          = -14112,
152  kIDHErrInvalidIndex           = -14113,
153  kIDHErrDeviceCantRead         = -14114,
154  kIDHErrDeviceCantWrite        = -14115,
155  kIDHErrCallNotSupported       = -14116
156};
157
158
159
160
161/* Holds Device Identification...*/
162typedef UInt32                          IDHDeviceID;
163enum {
164  kIDHInvalidDeviceID           = 0,
165  kIDHDeviceIDEveryDevice       = (long)0xFFFFFFFF
166};
167
168/* Values for 5 bit STYPE part of CIP header*/
169enum {
170  kIDHDV_SD                     = 0,
171  kIDHDV_SDL                    = 1,
172  kIDHDV_HD                     = 2,
173  kIDHDVCPro_25                 = 0x1E,
174  kIDHDVCPro_50                 = 0x1D
175};
176
177/*  Isoch Interval Atom Data*/
178struct IDHIsochInterval {
179  SInt32              duration;
180  TimeScale           scale;
181};
182typedef struct IDHIsochInterval         IDHIsochInterval;
183/* Need to fix this.  For now, cast this as a FWReferenceID*/
184typedef struct OpaquePsuedoID*          PsuedoID;
185/*
186   Isoch Device Status
187    This is atom-like, but isn�t an atom
188*/
189struct IDHDeviceStatus {
190  UInt32              version;
191  Boolean             physicallyConnected;
192  Boolean             readEnabled;
193  Boolean             writeEnabled;
194  Boolean             exclusiveAccess;
195  UInt32              currentBandwidth;
196  UInt32              currentChannel;
197  PsuedoID            localNodeID;            /*����may go in atoms */
198  SInt16              inputStandard;          /* One of the QT input standards*/
199  Boolean             deviceActive;
200  UInt8               inputFormat;            /* Expected STYPE of data from device*/
201  UInt32              outputFormats;          /* Bitmask for supported STYPE values, if version > 0x200*/
202};
203typedef struct IDHDeviceStatus          IDHDeviceStatus;
204/*
205   Isochronous Data Handler Events
206
207*/
208typedef UInt32 IDHEvent;
209enum {
210  kIDHEventInvalid              = 0,
211  kIDHEventDeviceAdded          = 1L << 0, /* A new device has been added to the bus*/
212  kIDHEventDeviceRemoved        = 1L << 1, /* A device has been removed from the bus*/
213  kIDHEventDeviceChanged        = 1L << 2, /* Some device has changed state on the bus*/
214  kIDHEventReadEnabled          = 1L << 3, /* A client has enabled a device for read*/
215  kIDHEventFrameDropped         = 1L << 4, /* software failed to keep up with isoc data flow*/
216  kIDHEventReadDisabled         = 1L << 5, /* A client has disabled a device from read*/
217  kIDHEventWriteEnabled         = 1L << 6, /* A client has enabled a device for write*/
218  kIDHEventReserved2            = 1L << 7, /* Reserved for future use*/
219  kIDHEventWriteDisabled        = 1L << 8, /* A client has disabled a device for write*/
220  kIDHEventEveryEvent           = (unsigned long)0xFFFFFFFF
221};
222
223
224typedef UInt32                          IDHNotificationID;
225struct IDHEventHeader {
226  IDHDeviceID         deviceID;               /* Device which generated event*/
227  IDHNotificationID   notificationID;
228  IDHEvent            event;                  /* What the event is*/
229};
230typedef struct IDHEventHeader           IDHEventHeader;
231
232
233
234/*
235   IDHGenericEvent
236    An IDH will often have to post events from at interrupt time.  Since memory
237    allocation cannot occur from the interrupt handler, the IDH can preallocate
238    storage needed for handling the event by creating some IDHGenericEvent items.
239    Subsequently, when an event is generated, the type of event (specified in the
240    IDHEventHeader) will dictate how the IDHGenericEvent should be interpretted.
241
242    IMPORTANT NOTE : This means that a specific event structure can NEVER be greater
243    than the size of the generic one.
244
245*/
246struct IDHGenericEvent {
247  IDHEventHeader      eventHeader;
248  UInt32              pad[4];
249};
250typedef struct IDHGenericEvent          IDHGenericEvent;
251/*
252   IDHDeviceConnectionEvent
253    For kIDHEventDeviceAdded or kIDHEventDeviceRemoved events.
254*/
255struct IDHDeviceConnectionEvent {
256  IDHEventHeader      eventHeader;
257};
258typedef struct IDHDeviceConnectionEvent IDHDeviceConnectionEvent;
259/*
260   IDHDeviceIOEnableEvent
261    For kIDHEventReadEnabled, kIDHEventReadDisabled, kIDHEventWriteEnabled, or
262    kIDHEventWriteDisabled.
263*/
264struct IDHDeviceIOEnableEvent {
265  IDHEventHeader      eventHeader;
266};
267typedef struct IDHDeviceIOEnableEvent   IDHDeviceIOEnableEvent;
268/*
269   IDHDeviceFrameDroppedEvent
270    For kIDHEventFrameDropped
271*/
272struct IDHDeviceFrameDroppedEvent {
273  IDHEventHeader      eventHeader;
274  UInt32              totalDropped;
275  UInt32              newlyDropped;
276};
277typedef struct IDHDeviceFrameDroppedEvent IDHDeviceFrameDroppedEvent;
278typedef CALLBACK_API_C( OSStatus , IDHNotificationProcPtr )(IDHGenericEvent *event, void *userData);
279
280typedef IDHNotificationProcPtr          IDHNotificationProc;
281typedef STACK_UPP_TYPE(IDHNotificationProcPtr)                  IDHNotificationUPP;
282struct IDHParameterBlock {
283  UInt32              reserved1;
284  UInt16              reserved2;
285  void *              buffer;
286  ByteCount           requestedCount;
287  ByteCount           actualCount;
288  IDHNotificationUPP  completionProc;
289  void *              refCon;
290  OSErr               result;
291};
292typedef struct IDHParameterBlock        IDHParameterBlock;
293struct IDHResolution {
294  UInt32              x;
295  UInt32              y;
296};
297typedef struct IDHResolution            IDHResolution;
298struct IDHDimension {
299  Fixed               x;
300  Fixed               y;
301};
302typedef struct IDHDimension             IDHDimension;
303
304/*
305 *  IDHGetDeviceList()
306 *
307 *  Availability:
308 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
309 *    CarbonLib:        in CarbonLib 1.3 and later
310 *    Non-Carbon CFM:   in IDHLib 1.0 and later
311 */
312extern ComponentResult
313IDHGetDeviceList(
314  ComponentInstance   idh,
315  QTAtomContainer *   deviceList);
316
317
318/*
319 *  IDHGetDeviceConfiguration()
320 *
321 *  Availability:
322 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
323 *    CarbonLib:        in CarbonLib 1.3 and later
324 *    Non-Carbon CFM:   in IDHLib 1.0 and later
325 */
326extern ComponentResult
327IDHGetDeviceConfiguration(
328  ComponentInstance   idh,
329  QTAtomSpec *        configurationID);
330
331
332/*
333 *  IDHSetDeviceConfiguration()
334 *
335 *  Availability:
336 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
337 *    CarbonLib:        in CarbonLib 1.3 and later
338 *    Non-Carbon CFM:   in IDHLib 1.0 and later
339 */
340extern ComponentResult
341IDHSetDeviceConfiguration(
342  ComponentInstance   idh,
343  const QTAtomSpec *  configurationID);
344
345
346/*
347 *  IDHGetDeviceStatus()
348 *
349 *  Availability:
350 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
351 *    CarbonLib:        in CarbonLib 1.3 and later
352 *    Non-Carbon CFM:   in IDHLib 1.0 and later
353 */
354extern ComponentResult
355IDHGetDeviceStatus(
356  ComponentInstance   idh,
357  const QTAtomSpec *  configurationID,
358  IDHDeviceStatus *   status);
359
360
361/*
362 *  IDHGetDeviceClock()
363 *
364 *  Availability:
365 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
366 *    CarbonLib:        in CarbonLib 1.3 and later
367 *    Non-Carbon CFM:   in IDHLib 1.0 and later
368 */
369extern ComponentResult
370IDHGetDeviceClock(
371  ComponentInstance   idh,
372  Component *         clock);
373
374
375/*
376 *  IDHOpenDevice()
377 *
378 *  Availability:
379 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
380 *    CarbonLib:        in CarbonLib 1.3 and later
381 *    Non-Carbon CFM:   in IDHLib 1.0 and later
382 */
383extern ComponentResult
384IDHOpenDevice(
385  ComponentInstance   idh,
386  UInt32              permissions);
387
388
389/*
390 *  IDHCloseDevice()
391 *
392 *  Availability:
393 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
394 *    CarbonLib:        in CarbonLib 1.3 and later
395 *    Non-Carbon CFM:   in IDHLib 1.0 and later
396 */
397extern ComponentResult
398IDHCloseDevice(ComponentInstance idh);
399
400
401/*
402 *  IDHRead()
403 *
404 *  Availability:
405 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
406 *    CarbonLib:        in CarbonLib 1.3 and later
407 *    Non-Carbon CFM:   in IDHLib 1.0 and later
408 */
409extern ComponentResult
410IDHRead(
411  ComponentInstance    idh,
412  IDHParameterBlock *  pb);
413
414
415/*
416 *  IDHWrite()
417 *
418 *  Availability:
419 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
420 *    CarbonLib:        in CarbonLib 1.3 and later
421 *    Non-Carbon CFM:   in IDHLib 1.0 and later
422 */
423extern ComponentResult
424IDHWrite(
425  ComponentInstance    idh,
426  IDHParameterBlock *  pb);
427
428
429/*
430 *  IDHNewNotification()
431 *
432 *  Availability:
433 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
434 *    CarbonLib:        in CarbonLib 1.3 and later
435 *    Non-Carbon CFM:   in IDHLib 1.0 and later
436 */
437extern ComponentResult
438IDHNewNotification(
439  ComponentInstance    idh,
440  IDHDeviceID          deviceID,
441  IDHNotificationUPP   notificationProc,
442  void *               userData,
443  IDHNotificationID *  notificationID);
444
445
446/*
447 *  IDHNotifyMeWhen()
448 *
449 *  Availability:
450 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
451 *    CarbonLib:        in CarbonLib 1.3 and later
452 *    Non-Carbon CFM:   in IDHLib 1.0 and later
453 */
454extern ComponentResult
455IDHNotifyMeWhen(
456  ComponentInstance   idh,
457  IDHNotificationID   notificationID,
458  IDHEvent            events);
459
460
461/*
462 *  IDHCancelNotification()
463 *
464 *  Availability:
465 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
466 *    CarbonLib:        in CarbonLib 1.3 and later
467 *    Non-Carbon CFM:   in IDHLib 1.0 and later
468 */
469extern ComponentResult
470IDHCancelNotification(
471  ComponentInstance   idh,
472  IDHNotificationID   notificationID);
473
474
475/*
476 *  IDHDisposeNotification()
477 *
478 *  Availability:
479 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
480 *    CarbonLib:        in CarbonLib 1.3 and later
481 *    Non-Carbon CFM:   in IDHLib 1.0 and later
482 */
483extern ComponentResult
484IDHDisposeNotification(
485  ComponentInstance   idh,
486  IDHNotificationID   notificationID);
487
488
489/*
490 *  IDHReleaseBuffer()
491 *
492 *  Availability:
493 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
494 *    CarbonLib:        in CarbonLib 1.3 and later
495 *    Non-Carbon CFM:   in IDHLib 1.0 and later
496 */
497extern ComponentResult
498IDHReleaseBuffer(
499  ComponentInstance    idh,
500  IDHParameterBlock *  pb);
501
502
503/*
504 *  IDHCancelPendingIO()
505 *
506 *  Availability:
507 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
508 *    CarbonLib:        in CarbonLib 1.3 and later
509 *    Non-Carbon CFM:   in IDHLib 1.0 and later
510 */
511extern ComponentResult
512IDHCancelPendingIO(
513  ComponentInstance    idh,
514  IDHParameterBlock *  pb);
515
516
517/*
518 *  IDHGetDeviceControl()
519 *
520 *  Availability:
521 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
522 *    CarbonLib:        in CarbonLib 1.3 and later
523 *    Non-Carbon CFM:   in IDHLib 1.0 and later
524 */
525extern ComponentResult
526IDHGetDeviceControl(
527  ComponentInstance    idh,
528  ComponentInstance *  deviceControl);
529
530
531/*
532 *  IDHUpdateDeviceList()
533 *
534 *  Availability:
535 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
536 *    CarbonLib:        in CarbonLib 1.3 and later
537 *    Non-Carbon CFM:   in IDHLib 1.0 and later
538 */
539extern ComponentResult
540IDHUpdateDeviceList(
541  ComponentInstance   idh,
542  QTAtomContainer *   deviceList);
543
544
545/*
546 *  IDHGetDeviceTime()
547 *
548 *  Availability:
549 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
550 *    CarbonLib:        in CarbonLib 1.4 and later
551 *    Non-Carbon CFM:   not available
552 */
553extern ComponentResult
554IDHGetDeviceTime(
555  ComponentInstance   idh,
556  TimeRecord *        deviceTime);
557
558
559/*
560 *  IDHSetFormat()
561 *
562 *  Availability:
563 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
564 *    CarbonLib:        in CarbonLib 1.5 and later
565 *    Non-Carbon CFM:   not available
566 */
567extern ComponentResult
568IDHSetFormat(
569  ComponentInstance   idh,
570  UInt32              format);
571
572
573/*
574 *  IDHGetFormat()
575 *
576 *  Availability:
577 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
578 *    CarbonLib:        in CarbonLib 1.5 and later
579 *    Non-Carbon CFM:   not available
580 */
581extern ComponentResult
582IDHGetFormat(
583  ComponentInstance   idh,
584  UInt32 *            format);
585
586
587
588/*
589 *  NewIDHNotificationUPP()
590 *
591 *  Availability:
592 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
593 *    CarbonLib:        in CarbonLib 1.4 and later
594 *    Non-Carbon CFM:   available as macro/inline
595 */
596extern IDHNotificationUPP
597NewIDHNotificationUPP(IDHNotificationProcPtr userRoutine);
598
599/*
600 *  DisposeIDHNotificationUPP()
601 *
602 *  Availability:
603 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
604 *    CarbonLib:        in CarbonLib 1.4 and later
605 *    Non-Carbon CFM:   available as macro/inline
606 */
607extern void
608DisposeIDHNotificationUPP(IDHNotificationUPP userUPP);
609
610/*
611 *  InvokeIDHNotificationUPP()
612 *
613 *  Availability:
614 *    Mac OS X:         in version 10.0 and later in DVComponentGlue.framework
615 *    CarbonLib:        in CarbonLib 1.4 and later
616 *    Non-Carbon CFM:   available as macro/inline
617 */
618extern OSStatus
619InvokeIDHNotificationUPP(
620  IDHGenericEvent *   event,
621  void *              userData,
622  IDHNotificationUPP  userUPP);
623
624
625/* selectors for component calls */
626enum {
627    kIDHGetDeviceListSelect                    = 0x0001,
628    kIDHGetDeviceConfigurationSelect           = 0x0002,
629    kIDHSetDeviceConfigurationSelect           = 0x0003,
630    kIDHGetDeviceStatusSelect                  = 0x0004,
631    kIDHGetDeviceClockSelect                   = 0x0005,
632    kIDHOpenDeviceSelect                       = 0x0006,
633    kIDHCloseDeviceSelect                      = 0x0007,
634    kIDHReadSelect                             = 0x0008,
635    kIDHWriteSelect                            = 0x0009,
636    kIDHNewNotificationSelect                  = 0x000A,
637    kIDHNotifyMeWhenSelect                     = 0x000B,
638    kIDHCancelNotificationSelect               = 0x000C,
639    kIDHDisposeNotificationSelect              = 0x000D,
640    kIDHReleaseBufferSelect                    = 0x000E,
641    kIDHCancelPendingIOSelect                  = 0x000F,
642    kIDHGetDeviceControlSelect                 = 0x0010,
643    kIDHUpdateDeviceListSelect                 = 0x0011,
644    kIDHGetDeviceTimeSelect                    = 0x0012,
645    kIDHSetFormatSelect                        = 0x0013,
646    kIDHGetFormatSelect                        = 0x0014
647};
648
649
650#if PRAGMA_STRUCT_ALIGN
651    #pragma options align=reset
652#elif PRAGMA_STRUCT_PACKPUSH
653    #pragma pack(pop)
654#elif PRAGMA_STRUCT_PACK
655    #pragma pack()
656#endif
657
658#ifdef __cplusplus
659}
660#endif
661
662#endif /* __ISOCHRONOUSDATAHANDLER__ */
663
664