# API - HAL

The hal API is made up of several subsystems that each operate independantly of one another. This document describes the available APIs and gives some advice and examples on the usage of each.

## General XBOX Functionality

FunctionDescription
void XReboot()Reboots the XBOX. Note that this reboot takes the XBOX right back to the very start of its boot cycle. You have some level of control over this. Check out the xboxkrnl library's call to HalReturnToFirmware function.
void XLaunchXBE(   char *xbePath ) Launches an XBE (replacing the currently running XBE). If the launch is successful, this method will not return. If there is an error, it returns and you will have to decide what to do.

 Parameter Description xbePath Fully qualified dos path of the XBE. Example: c:/foo/bar.xbe

void XSleep(   int milliseconds ) Sleeps for the specific number of milliseconds. At the moment, it is in a tight loop, so it is not very thread friendly. One of these days, I will get around to calling a proper xboxkrnl API (once I figure out which one it is)

 Parameter Description milliseconds The length of time to sleep

int XGetTickCount()Returns the current kernel tick count (which is the number of milliseconds since the XBOX was turned on).
int XCreateThread(   XThreadCallback callback,   void *args1,   void *args2 ); Creates and runs a new thread.

 Parameter Description callback The entry point of the thread function. It must be a static function that takes two void * paramaters args1 This will be passed to the callback function as the first parameter args2 This will be passed to the callback function as the second parameter

## File Access

All of the file access APIs return a status code that you should compare against STATUS_SUCCESS.

FunctionDescription
int XConvertDOSFilenameToXBOX(   char *dosFilename,   char *xboxFilename ) Converts a dos-style filename (c:/foo/bar.txt) into an XBOX-style path (\Device\Harddisk0\Partition2\foo\bar.txt).

 Parameter Description dosFilename The dos filename. Examples are c:\foo\bar.txt, .\foo\bar.txt, \foo\bar.txt xboxFilename The converted XBOX filename

int XCreateFile(   int *handle,   char *filename,   unsigned int desiredAccess,   unsigned int sharedMode,   unsigned int creationDisposition,   unsigned int flagsAndAttributes ) Opens a file. Note that the title of the function is slightly misleading in that this function may not actually create a file... it may just open an existing one (depending on the combination of the various parameters. For more information on the combinations of the various parameters, see the Microsoft CreateFile documentation.

 Parameter Description handle The handle to the opened file filename The file to open. Examples of supported filenames are: c:/blah.txt, blah.txt, d:\default.txt desiredAccess Bitwise OR of one or more of the following options: DELETE SYNCHRONIZE GENERIC_ALL GENERIC_EXECUTE GENERIC_WRITE GENERIC_READ sharedMode Bitwise OR of one or more of the following options: FILE_SHARE_READ FILE_SHARE_WRITE FILE_SHARE_DELETE creationDisposition Bitwise OR of one or more of the following options: CREATE_NEW CREATE_ALWAYS OPEN_EXISTING OPEN_ALWAYS TRUNCATE_EXISTING flagsAndAttributes Bitwise OR of one or more of the following options (normally, you would just use FILE_ATTRIBUTE_NORMAL): FILE_FLAG_OPEN_NO_RECALL FILE_FLAG_OPEN_REPARSE_POINT FILE_FLAG_POSIX_SEMANTICS FILE_FLAG_BACKUP_SEMANTICS FILE_FLAG_DELETE_ON_CLOSE FILE_FLAG_SEQUENTIAL_SCAN FILE_FLAG_RANDOM_ACCESS FILE_FLAG_NO_BUFFERING FILE_FLAG_OVERLAPPED FILE_FLAG_WRITE_THROUGH FILE_ATTRIBUTE_READONLY FILE_ATTRIBUTE_HIDDEN FILE_ATTRIBUTE_SYSTEM FILE_ATTRIBUTE_DIRECTORY FILE_ATTRIBUTE_ARCHIVE FILE_ATTRIBUTE_DEVICE FILE_ATTRIBUTE_NORMAL FILE_ATTRIBUTE_TEMPORARY FILE_ATTRIBUTE_SPARSE_FILE FILE_ATTRIBUTE_REPARSE_POINT FILE_ATTRIBUTE_COMPRESSED FILE_ATTRIBUTE_OFFLINE FILE_ATTRIBUTE_NOT_CONTENT_INDEXED FILE_ATTRIBUTE_ENCRYPTED FILE_ATTRIBUTE_VALID_FLAGS FILE_ATTRIBUTE_VALID_SET_FLAGS

int XReadFile(   int handle,   void *buffer,   unsigned int numberOfBytesToRead,   unsigned int *numberOfBytesRead ) Reads data from an already opened file.

 Parameter Description handle The handle to the opened file buffer The char buffer to put the data into numberOfBytesToRead How many bytes to read numberOfBytesRead How many bytes were actually read from the file

int XWriteFile(   int handle,   void *buffer,   unsigned int numberOfBytesToWrite,   unsigned int *numberOfBytesWritten ) Writes data to an already opened file.

 Parameter Description handle The handle to the opened file buffer The char buffer to get the data from numberOfBytesToWrite How many bytes to write numberOfBytesWritten How many bytes were actually written to the file

int XCloseHandle(   int handle ) Seems fairly obvious doesn't it? Closes the file.

 Parameter Description handle The handle to the opened file

int XGetFileSize(   int handle,   unsigned int *filesize ) Queries the file size of a given file.

 Parameter Description handle The handle to the opened file filesize This variable is updated with the file's size

int XSetFilePointer(   int handle,   int distanceToMove,   int *newFilePointer,   int moveMethod ) Seeks to a location within an open file.

 Parameter Description handle The handle to the opened file distanceToMove The distance to seek (can be negative). newFilePointer Updated with the new absolute offset within the file moveMethod One of the following options: FILE_BEGIN FILE_CURRENT FILE_END

int XRenameFile(   char *oldFilename,   char *newFilename ) Renames a file

 Parameter Description oldFilename The file to rename newFilename The new file name

int XCreateDirectory(   char *directoryName ) Create a new directory

 Parameter Description directoryName The directory name

int XDeleteFile(   char *filename ) Deletes a file.

 Parameter Description filename The name of the file to delete

int XDeleteDirectory(   char *directoryName ) Deletes a directory

 Parameter Description directoryName The name of the directory to delete

int XMountDrive(   char driveLetter,   char *directoryName ) Assigns the given drive letter to the directoryName.

 Parameter Description driveLetter The drive letter to assign. For example, 'd' directoryName The directory that will be referred to as driveLetter from now on (until next reboot). It should contain a trailing slash, but if you forget, one will be added for you.

unsigned int XFindFirstFile(   char *directoryName,   char *mask,   PXBOX_FIND_DATA findFileData ) Performs a very similar function to the Win32 FindFirstFile, in that it populates (for the first file within the directoryName directory) the findFileData data structure. Returns ERROR_INVALID_HANDLE if the directory is unable to be opened or is invalid, otherwise a valid file handle for the directory (which you should pass to XFindNextFile to get the next file in the list).

The elements of the data structure are:

 typedef struct _XBOX_FIND_DATA {   unsigned int dwFileAttributes;   long long ftCreationTime;   long long ftLastAccessTime;   long long ftLastWriteTime;   unsigned int nFileSize;   char cFileName[0x100]; } XBOX_FIND_DATA, *PXBOX_FIND_DATA; 

 Parameter Description directoryName The directory that contains the file you care about mask A mask for the files you want. For example, "*.xbe" for all XBE files or "*" for all files fileFileData The data structure that will be populated with the file details (name, size, etc)

int XFindNextFile(   unsigned int handle,   PXBOX_FIND_DATA findFileData ) Gets the next file from the directory that was opened using XFindFirstFile. Returns ERROR_NO_MORE_FILES if there are no more files, 0 otherwise.

 Parameter Description handle The handle that was returned from XFindFirstFile fileFileData The data structure that will be populated with the file details (name, size, etc)

int XFindClose(   unsigned int handle ) Closes the handle that was opened when calling XFindFirstFile

 Parameter Description handle The handle that was returned from XFindFirstFile

## Controllers

Currently only one pad is supported. Details of XPadState are as follows:
typedef struct
{
char reserved1;
unsigned char structsize;

char pad;       /* 1=up 2=down 4=left 8=right + bitwise OR combos */
char reserved2;
char keys[6];   /* A B X Y Black White */

unsigned char trig_left;
unsigned char trig_right;
short stick_left_x;
short stick_left_y;
short stick_right_x;
short stick_right_y;



FunctionDescription
void XInitInput(   XUSBControl *xcontrol ) Initialises the XBOX controller USB subsystem. This function must be called before calling any of the other controller functions.

 Parameter Description xcontrol A pointer to a control structure that will be initialised. This control structure will be used in subsequent calls.

void XGetPadInput(   XPadState *padState,   XUSBControl *xcontrol,   int padNumber ) Reads the current state of the XBOX controllers

 Parameter Description padState A pointer to a XPadState structure that will contain the current state xcontrol The pointer to the control structure padNumber Which pad number are you querying?

void XSetPadInput(   XPadState *padState,   XUSBControl *xcontrol,   int padNumber ) Updates the current state of the XBOX controllers (sends a message). This function is a bit dodgy at the moment... use at your own risk!

 Parameter Description padState A pointer to a XPadState structure xcontrol The pointer to the control structure padNumber Which pad number are you updating?

void XReleaseInput(   XUSBControl *xcontrol ) Shuts down the XBOX controller subsystem. If you call this, you will need to call XInitInput again before you can interact with the controllers.

 Parameter Description xcontrol The pointer to the control structure

## Video

FunctionDescription
DWORD XVideoGetEncoderSettings();Returns the current video encoder settings.
unsigned char* XVideoGetFB()Returns a pointer to the XBOX's raw video buffer.
VIDEO_MODE XVideoGetMode() Returns a structure that represents the current video mode. The elements of the structure are described below:

 typedef struct _VIDEO_MODE {   int width;   int height;   int bpp;   int refresh; } VIDEO_MODE; 

void XVideoSetFlickerFilter(   int level ); Sets the level of flicker filter to an appropriate level.

 Parameter Description level The level of flicker filter to apply (should be between X and X)

BOOL XVideoSetMode(   int width,   int height,   int bpp,   int refresh ); Requests that the video mode be set to the requested mode. This function does some validation to ensure that the requested parameters are valid. Typical invocations might be:

 XVideoSetMode(640, 480, 24, 50); /* for PAL */ XVideoSetMode(640, 480, 24, 60); /* for NTSC */ XVideoSetMode(720, 480, 24, 50); /* for PAL */ XVideoSetMode(720, 480, 24, 60); /* for NTSC */ 

Returns a boolean indicating whether the mode was able to be changed.

 Parameter Description width The desired screen width height The desired screen height bpp The desired screen bits per pixel refresh The desired refresh rate in Hz

void XVideoSetSoftenFilter(   BOOL enable ); Sets the soften filter

 Parameter Description enable Whether the soften filter should be enabled or not

void XVideoSetVideoEnable(   BOOL enable ); Enables the video subsystem

 Parameter Description enable Whether the video should be enabled

## Audio

The audio support is functional, but experimental. When using the audio subsystem the first thing you need to do is initialise by calling XAudioInit(). This does not actually start playing anything, though. To get that to work, you will need to call XAudioPlay() (and likewise, to temporarily pause, you call XAudioPause()).

However, it is not much good playing unless you have given it some data to play. To give data to the audio subsystem, you need to call XAudioProvideSamples(). There are two supported ways of calling this method:

1. Your application code can call XAudioProvideSamples() based on its own timing. It is your code's responsibility to make sure you are calling this function often enough.
2. You can register a callback when you initialise and the audio subsystem will invoke your callback function when it needs more data. This callback function provides the data using a call to XAudioProvideSamples().
FunctionDescription
void XAudioInit(   int sampleSizeInBits,   int numChannels,   XAudioCallback callback,   void *data ); Initialises the audio subsystem. It does not start playing though.

 Parameter Description sampleSizeInBits Currently ignored (only 16 bit samples are supported at the moment). Provided for future expandability numChannels Currently ignored (only 2 channels (stereo) are supported at the moment). Provided for future expandability callback If non-NULL, this is the function that will be called by the audio subsystem when it needs more data. data This will be passed to the callback function (if the callback is set) when it is invoked

int XAudioPlay()Tells the audio chip to start playing.
int XAudioPause()Tells the audio chip to pause
void XAudioProvideSamples(   unsigned char *buffer,   unsigned short bufferLength,   int isFinal ); Gives some more data to the audio subsystem to play. You should call this often enough so that the chip doesn't run out of data, but not faster than the audio chip can process it (48kHz). Using the callback parameter in XAudioInit() may help.

 Parameter Description buffer A pointer to the samples which need to match the sampleSizeInBits and numChannels. For example, a 16 bit stereo sample would be 4 bytes in the following order: [ Left LSB, Left MSB, Right LSB, Right MSB ] bufferLength The length of the data contained in buffer. isFinal If this the last lot of data to be played?