Supplied API documentation

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

Function Description
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.

Function Description
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;

  char padding[0x40];
} XPadState;
Function Description
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

Function Description
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().
Function Description
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?