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: DVFamily.h 25 26 Contains: xxx put contents here xxx 27 28 Version: xxx put version here xxx 29 30 Written by: Steve Smith 31 32 Copyright: � 1996-1999 by Apple Computer, Inc., all rights reserved. 33 34 File Ownership: 35 36 DRI: xxx put dri here xxx 37 38 Other Contact: xxx put other contact here xxx 39 40 Technology: xxx put technology here xxx 41 42 Writers: 43 44 (jkl) Jay Lloyd 45 (KW) Kevin Williams 46 (ck) Casey King 47 (RS) Richard Sepulveda 48 (CP) Collin Pieper 49 (CLP) Collin Pieper 50 (AW) Adrienne Wang 51 (SS) Steve Smith 52 53 Change History (most recent first): 54 55 <24> 6/17/99 jkl Added fwClientID to DVGetLocalFWReferenceID call to make the 56 fwClientID part of the device info so IDH can execute 57 getDeviceStandard by itself. 58 <23> 6/8/99 KW Added an another event for input. Will go away when DVFamilyLib 59 is dead of course. 60 <22> 1/15/99 ck Firewire.h should be FireWire.h 61 <21> 1/4/99 GDW Changed DVFamily names. 62 <20> 12/9/98 SS Added FireWire ID for the local node in the DVDeviceInfo struct. 63 Changed DVGetDeviceClock to return a component instead of a 64 component instance. 65 <19> 11/16/98 SS Rearranged some data structures to work better in mixed 66 environment (Premiere plugins use 68K alignment). Added 67 deviceIsOnline flag in deviceInfo for Kevin. 68 <18> 11/13/98 SS Added DVGetDeviceClock() proto. 69 <17> 9/24/98 RS Added bufferSize to DVIsochCompleteEventStruct structure. 70 <16> 9/17/98 SS Added generic dv event notification support. Removed AppleEvent 71 support. Minor DV API semantic changes. 72 <15> 9/10/98 SS Somewhat gratuitous semantic change in the DV API to further 73 abstract the implementation, specifically, from DVDeviceRefNum 74 to DVDeviceConnectionID, and from DVOpen/CloseDriver to 75 DVOpen/CloseDeviceConnection. 76 <14> 9/3/98 SS Checked in first pass of dv device info stuff. 77 <13> 3/23/98 RS Changed to registered error codes 78 <12> 3/12/98 SS Changed semantics of DV driver API to use deviceIDs and refNums 79 instead of driverIDs everywhere. 80 <11> 3/8/98 RS Added new call DVIsEnabled() to query if a device has already 81 been enabled. 82 <10> 2/26/98 CP Added new error code for driver busy errors 83 <9> 2/24/98 CP Added two new error codes returned only if your mean to the 84 driver... 85 <8> 2/4/98 CP Added new defines for device standards 86 <7> 1/21/98 SS Removed AVC enums, typedefs, structs and prototypes. Base 87 support is now for the DVDoAVCTransaction() call only. 88 <6> 1/19/98 CP Tossed out obsolete constants and structures and moved ones that 89 should be private to safety... 90 <5> 1/19/98 AW Added prototype for determining whether camera is still 91 searching for timecode 92 <4> 1/13/98 SS Added DriverID parameter to AVC helper routines. These routines 93 should probably be moved to a separate file. 94 <3> 1/12/98 GDW Fixed KernelID prob. 95 <2> 1/12/98 SS Checked in Collin's changes: added new API calls, reorganized 96 layout. 97 <1> 8/18/97 CLP first checked in 98 <1> 3/27/97 SS first checked in 99 <6> 3/27/97 SS Added macro & function prototype to check whether the Family Lib 100 is fully initialized, i.e. determine if there are any FW devices 101 to control. 102 <5> 3/3/97 AW Added AVC Commands for getting/setting signals 103 <4> 2/19/97 SS Updated to 1.0a2 FSL 104 <3> 2/12/97 AW Updated to 1.0d18 FSL 105 <2> 10/31/96 SS Updated to Blaze d16 API. Added helper APIs for device control. 106 107*/ 108 109// 110// DVFamily.h 111// 112 113#ifndef __DVFAMILY__ 114#define __DVFAMILY__ 115 116#include <Types.h> 117#include <NameRegistry.h> 118#include <DriverServices.h> 119#include <AppleEvents.h> 120#include <Components.h> 121 122#include "FireWire.h" 123 124#ifdef __cplusplus 125extern "C" { 126#endif 127 128/////////////////////////////////////////////////////////////////////// 129// 130// constants 131// 132/////////////////////////////////////////////////////////////////////// 133 134enum 135{ 136 kInvalidDVDeviceID = 0, 137 kInvalidDVConnectionID = 0 138}; 139 140enum 141{ 142 kDVDisconnectedErr = -14101, 143 kDVBadIDErr = -14102, 144 kUnknownStandardErr = -14103, 145 kAlreadyEnabledErr = -14104, 146 kNotEnabledErr = -14105, 147 kDVDeviceBusyErr = -14106 148}; 149 150enum 151{ 152 kUnknownStandard = 0, 153 kNTSCStandard = 1, 154 kPALStandard = 2 155}; 156 157// DV events 158enum 159{ 160 kInvalidDVDeviceEvent = 0, 161 162 kDVDeviceAdded = 1 << 0, 163 kDVDeviceRemoved = 1 << 1, 164 KDVDeviceInfoChanged = 1 << 2, 165 166 kDVIsochReadEnabled = 1 << 3, 167 kDVIsochReadComplete = 1 << 4, 168 kDVIsochReadDisabled = 1 << 5, 169 170 kDVIsochWriteEnabled = 1 << 6, 171 kDVIsochWriteComplete = 1 << 7, 172 kDVIsochWriteDisabled = 1 << 8, 173 174 kDVAVCEnabled = 1 << 9, 175 kDVAVCDisabled = 1 << 10, 176 kDVAVCTransactionComplete = 1 << 11, 177 178 // Tempory new event for input. Goes away DVFamily is dead. 179 kDVInputEvent = 1 << 12, 180 181 kDVEveryEvent = 0x00001fff 182}; 183 184enum 185{ 186 kDVGlobalEventConnectionID = 0xffffffff, 187 kEventSpecificDataSize = 16 188}; 189 190/////////////////////////////////////////////////////////////////////// 191// 192// types 193// 194/////////////////////////////////////////////////////////////////////// 195 196// holds our device identification... 197typedef UInt32 DVCDeviceID; 198 199// holds our device connection identification... 200typedef UInt32 DVCDeviceConnectionID; 201 202// holds info about device's isoch channels 203typedef struct DVCIsochChannelStatus { 204 UInt32 fwChannelNum; 205 UInt32 speed; 206 UInt32 signalType; 207 Boolean isEnabled; 208 UInt8 rsvd[3]; // alignment padding for 68k 209} DVCIsochChannelStatus, *DVCIsochChannelStatusPtr; 210 211// holds info about device 212typedef struct DVCDeviceInfo { 213 DVCDeviceID dvDeviceID; 214 CSRNodeUniqueID uniqueID; 215 UInt32 vendorID; 216 RegEntryID regEntryID; 217 Boolean deviceIsOnline; 218 Boolean AVCisEnabled; 219 UInt16 rsvd; // alignment padding for 68k 220 DVCIsochChannelStatus readChannel; 221 DVCIsochChannelStatus writeChannel; 222 Str255 deviceName; 223 FWReferenceID localNodeID; // FW reference ID for local node 224 // (i.e. FW interface) 225 FWReferenceID fwClientID; 226 227} DVCDeviceInfo, *DVCDeviceInfoPtr; 228 229// for sending AVC commands 230typedef struct AVCTransactionParamsStruct { 231 Ptr commandBufferPtr; 232 UInt32 commandLength; 233 Ptr responseBufferPtr; 234 UInt32 responseBufferSize; 235 FCPResponseHandlerPtr responseHandler; 236} AVCTransactionParams, *AVCTransactionParamsPtr; 237 238/////////////////////////////////////////////////////////////////////// 239// 240// DV Event Notification 241// 242 243typedef struct OpaqueRef *DVCNotificationID; 244 245typedef struct DVCEventHeaderStruct { 246 DVCDeviceID deviceID; // who it's from 247 DVCNotificationID notifID; 248 UInt32 theEvent; // what the event was 249} DVCEventHeader, *DVCEventHeaderPtr; 250 251typedef struct DVCEventRecordStruct { // generalized form 252 DVCEventHeader eventHeader; 253 UInt8 eventData[kEventSpecificDataSize]; 254} DVCEventRecord, *DVCEventRecordPtr; 255 256typedef struct DVCConnectionEventStruct { 257 DVCEventHeader eventHeader; 258} DVCConnectionEvent, *DVCConnectionEventPtr; 259 260typedef struct DVCIsochCompleteEventStruct { 261 DVCEventHeader eventHeader; 262 Ptr pFrameBuffer; 263 unsigned long bufferSize; 264 UInt32 fwCycleTime; 265} DVCIsochCompleteEvent, *DVCIsochCompleteEventPtr; 266 267typedef struct DVCAVCTransactionCompleteEventStruct { 268 DVCEventHeader eventHeader; 269 Ptr commandBufferPtr; 270 UInt32 commandLength; 271 Ptr responseBufferPtr; 272 UInt32 responseBufferSize; 273} DVCAVCTransactionCompleteEvent, *DVAVCTransactionCompleteEventPtr; 274 275// DV notification proc 276typedef OSStatus (*DVCNotifyProc)( DVCEventRecordPtr event, 277 void *userData ); 278 279/////////////////////////////////////////////////////////////////////// 280// 281// external prototypes 282// 283/////////////////////////////////////////////////////////////////////// 284 285/////////////////////////////////////////////////////////////////////// 286// 287// general device management 288// 289UInt32 DVCCountDevices( void ); 290OSErr DVCGetIndDevice( DVCDeviceID * pDVDevice, UInt32 index ); 291OSErr DVCGetDeviceInfo( DVCDeviceID deviceID, DVCDeviceInfoPtr pInfo ); 292 293OSErr DVCSetDeviceName( DVCDeviceID deviceID, char * str ); 294OSErr DVCGetDeviceName( DVCDeviceID deviceID, char * str ); 295 296OSErr DVCOpenDeviceConnection( DVCDeviceID deviceID, DVCDeviceConnectionID *pConnID ); 297OSErr DVCCloseDeviceConnection( DVCDeviceConnectionID connID ); 298 299OSErr DVCGetDeviceClock( DVCDeviceID deviceID, Component *clock ); 300 301/////////////////////////////////////////////////////////////////////// 302// 303// DV event notification 304// 305OSErr DVCNewNotification( DVCDeviceConnectionID connID, DVCNotifyProc notifyProc, 306 void *userData, DVCNotificationID *pNotifyID ); 307 308OSErr DVCNotifyMeWhen( DVCDeviceConnectionID connID, DVCNotificationID notifyID, UInt32 events); 309OSErr DVCCancelNotification( DVCDeviceConnectionID connID, DVCNotificationID notifyID ); 310OSErr DVCDisposeNotification( DVCDeviceConnectionID connID, DVCNotificationID notifyID ); 311 312/////////////////////////////////////////////////////////////////////// 313// 314// DV Isoch Read 315// 316OSErr DVCEnableRead( DVCDeviceConnectionID connID ); 317OSErr DVCDisableRead( DVCDeviceConnectionID connID ); 318OSErr DVCReadFrame( DVCDeviceConnectionID connID, Ptr *ppReadBuffer, UInt32 * pSize ); 319OSErr DVCReleaseFrame( DVCDeviceConnectionID connID, Ptr pReadBuffer ); 320 321/////////////////////////////////////////////////////////////////////// 322// 323// DV Isoch Write 324// 325OSErr DVCEnableWrite( DVCDeviceConnectionID connID ); 326OSErr DVCDisableWrite( DVCDeviceConnectionID connID ); 327OSErr DVCGetEmptyFrame( DVCDeviceConnectionID connID, Ptr *ppEmptyFrameBuffer, UInt32 * pSize ); 328OSErr DVCWriteFrame( DVCDeviceConnectionID connID, Ptr pWriteBuffer ); 329 330/////////////////////////////////////////////////////////////////////// 331// 332// AVC transactions 333// 334OSErr DVCEnableAVCTransactions( DVCDeviceConnectionID connID ); 335OSErr DVCDoAVCTransaction( DVCDeviceConnectionID connID, AVCTransactionParamsPtr pParams ); 336OSErr DVCDisableAVCTransactions( DVCDeviceConnectionID connID ); 337 338/////////////////////////////////////////////////////////////////////// 339// 340// to be discontinued... 341// 342OSErr DVCIsEnabled( DVCDeviceConnectionID connID, Boolean *isEnabled); 343OSErr DVCGetDeviceStandard( DVCDeviceConnectionID connID, UInt32 * pStandard ); 344 345 346 347 348#ifdef __cplusplus 349} 350#endif 351 352#endif __DVFAMILY__ 353 354 355