Helix Client OS Abstractions

Contents

Helix Client OS Abstractions

This document outlines the various OS abstractions that exist in the Helix codebase. A description of each abstraction is given along with porting hints, source file locations, and unit test information.

Most platform specific code will be contained in subdirectories of the librarys platform directory. For example any platform specific code for the library in common/system will be contained in subdirectories of common/system/platform. The Symbian specific code for this library is contained in common/system/platform/symbian while the Mac related code is in common/system/platform/mac. Sometimes platform specific code will work for a group of platforms. In this case a generic subdirectory name is used. An example of this case would be the common/system/platform/unix directory. This directory contains OS specific code for various flavors of Unix-like operating systems.

DLL Abstractions

o DLLAccess

Thread Abstractions

o HXThread

o HXMutex

o HXEvent

o HXAsyncTimer

File Abstractions

o CHXFileSpecUtils

o CHXDataFile

o CHXDirectory

o CFindFile

Audio Abstractions

o CHXAudioDevice

Video Abstractions

o CMiniBaseSite

o CMiniBaseSurface

Network Abstractions

o conn

o HXNetworkServices

DLL Abstractions:

DLLAccess

Description:

The DLLAccess abstraction hides the details associated with loading DLL. It provides a simple interface for opening and closing DLLs and retrieving pointers to DLL symbols.

Source Location:

common/system/dllacces.cpp, common/system/pub/dllacces.h

Porting Information:

Most platforms have their own APIs for loading DLLs and retrieving the symbol pointers. A platform must create an object that derives from the DLLAccessImp class that is defined in common/system/pub/dllaccess.h.

Unit Test Information:

The unit test for DLLAccess is located in common/system/test. The test executable is called tdllaccess. You may need to create your own tdllaccess.in file for your platform. This is needed because platforms dont always use the same extensions for DLLs and dont report the same error messages when DLL loading or symbol lookups fail.

Thread Abstractions:

HXThread

Description:

The HXThread abstraction hides all the OS specific details of thread creation, thread management, and thread info. It also contains a mechanism for passing messages to the thread represented by the HXThread object.

Source Location:

common/system/pub/hxthread.h, common/system/hxthread.cpp

Porting Information:

For each target platform, an object that derives from HXThread must be created. HXThread::MakeThread() must then be modified to create an instance of this derived object only when common/system/hxthread is built for that target platform. The message passing part of this objects interface is heavily modeled after the Windows message passing mechanism. Unfortunately this means that for non-Windows platforms equivalent functionality must be implemented.

Unit Test Information:

The HXThread unit test is called tthreads and is located in common/system/test. This unit test has not been made overly cross platform yet. Some porting work may be needed to get it running on the target platform.

HXMutex

Description:

The HXMutex abstraction hides the details of the OS specific mutex implementation.

Source Location:

common/system/pub/hxthread.h, common/system/hxthread.cpp

Porting Information:

For each platform, an object that derives from HXMutex must be created. HXMutex::MakeMutex() must also be modified to create an instance of this derived object only when common/system/hxthread.cpp is built for the target platform. The HXMutex implementation must allow recursive locking. Some OS native mutex implementations do not support recursive locking so the derived object must provide this functionality.

Unit Test Information:

Currently the HXMutex unit test code is contained in the HXThread unit test. See the HXThread Unit Test Information section for details.

HXEvent

Description:

The HXEvent abstraction hides the details of the OS specific condition variable implementation.

Source Location:

common/system/pub/hxthread.h, common/system/hxthread.cpp

Porting Information:

For each platform, an object that derives from HXEvent must be created. HXEvent::MakeEvent() must also be modified to create an instance of this derived object only when common/system/hxthread.cpp is built for the target platform.

Unit Test Information:

Currently the HXEvent unit test code is contained in the HXThread unit test. See the HXThread Unit Test Information section for details.

HXAsyncTimer

Description:

The HXAsyncTimer abstraction is used for scheduling and canceling asynchronous timer events. This abstraction is used the player timeline objects get regular callbacks from the OS.

Source Location:

common/system/pub/hxthread.h, common/system/hxthread.cpp

Porting Information:

This abstraction is heavily modeled after the Windows asynchronous timer interface. Platforms usually have to maintain the timerID to callback function mapping in a static map variable. You can see an example of this in the unix implementation located in common/system/platform/unix/UnixThreads.cpp.

Unit Test Information:

The unit test for HXAsyncTimer is called tasynctimer and is located in common/system/test. This unit test will require a little platform specific porting. Each platform will need to implement HXAsyncTimerTest::ProcessEvents() and HXAsyncTimerTest::SchedulerQuantum(). You can see examples of these functions in common/system/test/platform/unix/unix_async_test.cpp and common/system/test/platform/symbian/symbian_async_test.cpp.

File Abstractions:

CHXFileSpecUtils

Description:

Hides the details of how the OS performs various filesystem operations. This class can be used to get the total disk space, get the amount of disk space free, create directories, remove directories, check for the existence of files and many other operations.

Source Location:

common/fileio/pub/filespecutils.h

Porting Information:

This class has a very wide interface and the client core does not use most of the functions. You might want to look at the Symbian implementation in common/fileio/platform/symbian to see which functions are actually used by the core.

Unit Test Information:

No unit test available.

CHXDataFile

Description:

This abstraction hides the OS specific details of doing file I/O.

Source Location:

common/fileio/pub/chxdataf.h, common/fileio/chxdataf.cpp, common/include/hxdataf.h

Porting Information:

Most platforms just create a derived class of CHXDataFile and implement its interface. The Symbian port implements a class that implements the IHXDataFile interface and then uses a class called CCHX2IHXDataFile to adapt the IHXDataFile interface to the CHXDataFile interface. Future ports should use a method similar to the Symbian port.

Unit Test Information:

The unit test for this code is called tihxfile and is located in common/fileio/test.

CHXDirectory

Description:

The CHXDirectory abstraction hides details about how to manipulate directories.

Source Location:

common/fileio/pub/hxdir.h, common/fileio/platform/*

Porting Information:

Each platform defines its own implementation of CHXDirectory. Most platforms have just copied the class declaration from a previous port and changed the parts that they needed to. This is a less than idea situation, but it is how things must be until we refactor this abstraction.

Unit Test Information:

The CHXDirectory unit test code is contained in the CHXDataFile unit test. See the CHXDataFile Unit Test Information section for details.

CFindFile

Description:

The CFindFile abstraction hides the details of searching a directory for files that match a particular pattern.

Source Location:

common/fileio/pub/findfile.h, common/fileio/findfile.cpp

Porting Information:

For each platform, an object that derives from CFindFile must be created. CFindFile::CreateFindFile() must also be modified to create an instance of this derived object only when common/findfile.cpp is built for the target platform.

Unit Test Information:

No unit test available

Audio Abstractions:

CHXAudioDevice

Description:

The CHXAudioDevice hides the details of the OS specific audio APIs.

Source Location:

audio/device/pub/hxaudev.h, audio/device/hxaudev.cpp

Porting Information:

For each platform, an object that derives from CHXAudioDevice must be created. CHXAudioDevice::Create() must also be modified to create an instance of this derived object only when audio/device/hxaudev.cpp is built for the target platform.

Unit Test Information:

The audio device unit test is called testauddevice and it is located in audio/device/test.

Video Abstractions:

CMiniBaseSite

Description:

The CMiniBaseSite abstraction hides the OS specific details of managing the video window.

Source Location:

video/sitelib/pub/minisite.h, video/sitelib/minisite.cpp

Porting Information:

For each platform, an object that derives from CMiniBaseSite must be created. CMiniBaseSite::CreateSite() must also be modified to create an instance of this derived object only when video/sitelib/minisite.cpp is built for the target platform.

Unit Test Information:

No unit test available

CMiniBaseSurface

Description:

The CMiniSurface abstraction hides details about how to write video data to the screen.

Source Location:

video/sitelib/pub/minisurf.h, video/sitelib/minisurf.cpp

Porting Information:

For each platform, an object that derives from CMiniBaseSurface must be created. CMiniBaseSurface::Create () must also be modified to create an instance of this derived object only when video/sitelib/minisurf.cpp is built for the target platform.

Unit Test Information:

No unit test is available.

Network Abstractions:

conn

Description:

The conn abstraction hides the details of the OS socket API. Along with the standard static object creation function, this abstraction contains static functions to initialize and shutdown the OS specific socket API. The conn interface is basically a BSD socket API wrapper that also has a few extra functions related to DNS lookup.

Source Location:

common/netio/pub/conn.h, common/netio/conn.cpp

Porting Information:

This abstraction should only be ported if your target platform has a socket API that is similar to the BSD API. This abstraction works best for socket APIs that dont use an asynchronous callback mechanism for I/O notification. If you decide to port the conn abstraction, then you dont need to worry about porting HXNetworkServices. The HXNetworkServices implementation that uses the conn abstraction is built by default. Linux, Windows, and Mac platforms use this layer to abstract its network I/O functionality.

Unit Test Information:

No unit test is available.

HXNetworkServices

Description:

HXNetworkServices implements the IHXNetworkServices interface which is the abstraction that the rest of the Helix codebase uses for network I/O. This object is responsible for creating objects that implement the IHXResolver, IHXTCPSocket, and IHXUDPSocket interfaces.

Source Location:

client/netwksvc/pub/hxnetapi.h, client/netwksvc/hxnetapi.cpp

Porting Information:

On platforms where the socket API uses an asynchronous callback mechanism for handling network I/O notification, it is better to create a platform specific implementation of the HXNetworkServices object. This object should create platform specific classes that support the IHXResolver, IHXTCPSocket, and IHXUDPSocket interfaces. The source files mentioned in the source location section point to the implementation of HXNetworkServices that uses the conn abstraction to handle network I/O. If you are porting the conn abstraction, these files provide information about how the conn methods will be called. If you want an example of how to implement your own HXNetworkServices objects, look at the code in client/netwksvc/platform/symbian. Symbians socket API uses asynchronous callbacks for network I/O so it is a perfect example for showing when it is appropriate to port HXNetworkServices instead of the conn abstraction.

Unit Test Information:

No unit test is available.


Copyright 1995-2004 RealNetworks, Inc. All rights reserved. RealNetworks and Helix are trademarks of RealNetworks.
All other trademarks or registered trademarks are the property of their respective holders.