design.txt

linux下的一款播放器

/* ***** BEGIN LICENSE BLOCK *****
 * Source last modified: $Id: design.txt,v 1.1.14.1 2004/07/19 21:04:31 hubbe Exp $
 * 
 * Portions Copyright (c) 1995-2004 RealNetworks, Inc. All Rights Reserved.
 * 
 * The contents of this file, and the files included with this file,
 * are subject to the current version of the RealNetworks Public
 * Source License (the "RPSL") available at
 * http://www.helixcommunity.org/content/rpsl unless you have licensed
 * the file under the current version of the RealNetworks Community
 * Source License (the "RCSL") available at
 * http://www.helixcommunity.org/content/rcsl, in which case the RCSL
 * will apply. You may also obtain the license terms directly from
 * RealNetworks.  You may not use this file except in compliance with
 * the RPSL or, if you have a valid RCSL with RealNetworks applicable
 * to this file, the RCSL.  Please see the applicable RPSL or RCSL for
 * the rights, obligations and limitations governing use of the
 * contents of the file.
 * 
 * Alternatively, the contents of this file may be used under the
 * terms of the GNU General Public License Version 2 or later (the
 * "GPL") in which case the provisions of the GPL are applicable
 * instead of those above. If you wish to allow use of your version of
 * this file only under the terms of the GPL, and not to allow others
 * to use your version of this file under the terms of either the RPSL
 * or RCSL, indicate your decision by deleting the provisions above
 * and replace them with the notice and other provisions required by
 * the GPL. If you do not delete the provisions above, a recipient may
 * use your version of this file under the terms of any one of the
 * RPSL, the RCSL or the GPL.
 * 
 * This file is part of the Helix DNA Technology. RealNetworks is the
 * developer of the Original Code and owns the copyrights in the
 * portions it created.
 * 
 * This file, and the files included with this file, is distributed
 * and made available on an 'AS IS' basis, WITHOUT WARRANTY OF ANY
 * KIND, EITHER EXPRESS OR IMPLIED, AND REALNETWORKS HEREBY DISCLAIMS
 * ALL SUCH WARRANTIES, INCLUDING WITHOUT LIMITATION, ANY WARRANTIES
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, QUIET
 * ENJOYMENT OR NON-INFRINGEMENT.
 * 
 * Technology Compatibility Kit Test Suite(s) Location:
 *    http://www.helixcommunity.org/content/tck
 * 
 * Contributor(s):
 * 
 * ***** END LICENSE BLOCK ***** */

Cross Platform:

	Classes and functions implemented to remove dependency on Helix static lib's,
	 minimizing module's size for linkers not implementing dead stripping.
	 Used exclusively within hxclientkit:

		CHXClientUnknown - IUnknown implementation.
		CHXClientBuffer - Complete IHXBuffer implementation.
		CHXClientRequest - Complete IHXRequest implementation.
			Created by CHXClientPlayer to route OpenURL() requests through IHXPlayer --> IHXPlayer2::OpenRequest().
		CHXMimeTypeHeader - Partial IHXValues implementation
			Created by CHXClientRequest as the ResponseHeaders for a IHXRequest.
		CHXFlatArray - Flat array data structure for storage and fast retrieval of records.
		HXDebugStub - Debug only build. Included to quiet link errors.
	
	Module's central logic classes and functions.
	
		CHXClientPlayer - Wrapper for IHXPlayer.
			Supports IHXClientPlayer, defined in hxclientkit, to access Player functionality.
		CHXClientEngine - Wrapper IHXClientEngine implementation and base class for Platform specific logic
			Platform specific derived class must implement pure virtual methods and define CreatePlatformClientEngine(),
			 which should just return a newly created instance of the derived class.
		CHXClientContext - IHXPlayer Client Context
			Created by CHXClientPlayer and registered with IHXPlayer::SetClientContext().
		CHXClientEngineContext - IHXClientEngine Context
			Created by CHXClientEngine and passed to IHXClientEngine --> IHXClientEngineSetup::Setup().
		CHXClientSink - IHXPlayer Client Advise Sink
			Created by CHXClientPlayer and registered with IHXPlayer::AddAdviseSink() and IHXPlayer --> IHXGroupManager::AddSink().
		CHXClientSiteSupplier - IHXSiteSupplier implementation.
			Created by CHXClientPlayer and passed to CHXClientContext; QI'd by Helix through Client Context.
		CHXClientSite - Wrapper for all Sites requested by Helix.
			Created by CHXClientSiteSupplier.
			Creates/Destroys IHXSite's and implements IHXSiteWatcher to observe its created site.
		CHXClientDataStream - Support for streaming data to Player, ie http content streamed by browser to embedded plugin
			Created by CHXClientPlayer
		CHXEQProcessor - IHXAudioHook implementation to support Equalizer (EQ).
			Created by CHXClientPlayer.
			Receives audio packets and routes to HXEQEngine.
		HXEQEngine - EQ packet processing engine.
		CHXStatisticTracker - Collection of classes used to track Statistics.
			Root instance created by CHXClientPlayer
		enter/exit_hx_headers.h - Used to wrap #includes of Helix headers. On Mac, prevent BOOL name collisions.
		HXErrorCodeStrings - Mapping between HXRESULT and error string.
		HXClientGuids - Required GUID definitions for hxclientkit.
	
	Public Headers
	
		HXClientCallbacks.h - Struct of function ptr callbacks.
			Every function ptr is optional; pass NULL if not implemented.
			HXClientCallbacks: Implemented by TLC to observe state changes and listen to Helix feedback for a particular Player instance.
			HXStatisticsCallbacks: Implemented by TLC to observe changes in specified Helix statistics
			HXClientEngineCallbacks: Implemented by TLC to respond to Client Engine specific feedback
		HXClientCProcPtrs.h - C API ProcPtr typedef's
			Used when this module is explicitly loaded and its C exported functions are specifically read in.
		HXClientCFuncs.h - C API's
			Includes platform specific function to route native events to Helix; required on at least Mac and Unix. Implementation in CHXClientEngine<Platform>
		HXClientCOMAccess.h - Access to Helix Player and Client Engine's IUnknown's.
			Use if functionality cannot be accessed otherwise.
		HXClientConstants.h - Module Constants
		HXClientTypes.h - Module Types. Intended to cut #include dependency of TLC's on all other Helix modules.
		
	C API Getting Started Example
	
		HXClientCallbacks myClientCallbacks =
		{
			... // Fill in all the function pointers for the methods you want called; pass NULL for those you don't
		};
		SHXClientWindow myClientWindow; // This needs to persist for the life of the client player instance. Updated by TLC as necessary.
		
		HXClientPlayerToken clientPlayerToken;
		ClientPlayerCreate( &clientPlayerToken, &myClientWindow, pTokenPassedToCallbackMethods, &myClientCallbacks );
			// Interfaces with CHXClientEngine to create client engine, if necessary.
			// Creates IHXPlayer and passes to new instance of CHXClientPlayer.
		ClientPlayerOpenURL( clientPlayerToken, pURL, pMimeType ); // mime type can be NULL.
	
Platform specific - Mac OS X Cocoa:

	Public Objective-C classes
	
		HXClientPlayer - Objective-C wrapper for a CHXClientPlayer instance.
			init... selectors handle all the details of creating a usable CHXClientPlayer instance.
			observer object passed to init... selectors implements its desired callbacks. No HXClientCallbacks struct is required.
		HXClientView - Objective-C Cocoa NSView derived class for managing a HXClientPlayer's window real estate.
			Responsible for keeping Helix's SHXClientWindow (HXxWindow) up to date, forcing screen updates as necessary, and routing applicable mouse & key events.
			NOT responsible for maintaining content aspect ratio.
		HXClientEngine - Objective-C wrapper for a CHXClientEngineMac instance.
			Created/Released by HXClientPlayer.
			Singleton accessed through [HXClientEngine sharedClientEngine] selector.
			Doesn't typically need to be accessed by TLC.

	Internal classes and functions
	
		CHXClientEngineMac - Required CHXClientEngine derived class.
			Loads/Unloads Client Core executable .bundle.
			Initializes Client Core's DLL Access paths for "DT_Common", "DT_Plugins", and "DT_Codecs" through accessing exported "SetDLLAccessPath" function.
			Creates/Closes singleton instance of IHXClientEngine through accessing exported "CreateEngine" and "CloseEngine" functions.
		CHXStatisticObserverBridge - Converter between HXStatisticsCallbacks and Objective-C selectors implemented in HXClientPlayer's observer.
			Created by HXClientPlayer.
		HXErrorCodeStringsMac - Responsible for mapping error string from HXErrorCodeStrings into a localizable Mac CFStringRef.
		HXEventRecordUtils - Classic EventRecord utilities. Converter between Cocoa (NSEvent) and Carbon (EventRecord) event.
			Helix handles events as EventRecord's.
		HXPlayerToObserver - Converter between HXClientCallbacks and Objective-C selectors implemented in HXClientPlayer's observer.
			Used by HXClientPlayer.
		HXStringUtils - Mac string utilities.
		
	Cocoa Getting Started Example
	
		Create .nib file which optionally includes a HXClientView
			Add a "CustomView" to the .nib and set its "Custom Class" to HXClientView (After dragging HXClientView.h to the .nib)
		Create a Controller that init's and owns the HXClientPlayer and serves as its observer.
		Add an outlet to the Controller that connects to your HXClientView, ie
			IBOutlet HXClientView* clientView;
		Call either
			[[HXClientPlayer alloc] initInView:clientView withObserver:self]
		or
			[[HXClientPlayer alloc] initInWindow:NULL withObserver:self] // TLC doesn't support visual portions of content, audio will still play.
			
		See player/app/mac for a sample Cocoa Player.
	
	HXClientKit.framework - executable output
	
		Module is created as a standard Mac Mach-O Framework
		It is intended to be copied into an application package's "Contents/Frameworks" folder.
			See player/app/mac's Umakefil for how to include this Framework in an application via ribosome.
		The Helix Client Core executable code is copied into this Framework's "HelixPlugins" folder.
			Three subfolders are created which map to the DLL Access paths set by CHXClientEngineMac: