# 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
`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.
`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
`XGetTickCount()` | Returns the current kernel tick count (which is the number of milliseconds since the XBOX was turned on).

## File Access

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

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

## 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
`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.
`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?
`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?
`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

Back to Home Page