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