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
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)

ParameterDescription
millisecondsThe 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.

FunctionDescription
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.

ParameterDescription
handleThe handle to the opened file
filenameThe file to open. Examples of supported filenames are: c:/blah.txt, blah.txt, d:\default.txt
desiredAccessBitwise OR of one or more of the following options:
  • DELETE
  • SYNCHRONIZE
  • GENERIC_ALL
  • GENERIC_EXECUTE
  • GENERIC_WRITE
  • GENERIC_READ
sharedModeBitwise OR of one or more of the following options:
  • FILE_SHARE_READ
  • FILE_SHARE_WRITE
  • FILE_SHARE_DELETE
creationDispositionBitwise OR of one or more of the following options:
  • CREATE_NEW
  • CREATE_ALWAYS
  • OPEN_EXISTING
  • OPEN_ALWAYS
  • TRUNCATE_EXISTING
flagsAndAttributesBitwise 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.

ParameterDescription
handleThe handle to the opened file
bufferThe char buffer to put the data into
numberOfBytesToReadHow many bytes to read
numberOfBytesReadHow 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.

ParameterDescription
handleThe handle to the opened file
bufferThe char buffer to get the data from
numberOfBytesToWriteHow many bytes to write
numberOfBytesWrittenHow many bytes were actually written to the file

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

ParameterDescription
handleThe handle to the opened file

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

ParameterDescription
handleThe handle to the opened file
filesizeThis 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.

ParameterDescription
handleThe handle to the opened file
distanceToMoveThe distance to seek (can be negative).
newFilePointerUpdated with the new absolute offset within the file
moveMethodOne of the following options:
  • FILE_BEGIN
  • FILE_CURRENT
  • FILE_END

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

ParameterDescription
oldFilenameThe file to rename
newFilenameThe new file name

int XCreateDirectory(
  char *directoryName
)
Create a new directory

ParameterDescription
directoryNameThe directory name

int XDeleteFile(
  char *filename
)
Deletes a file.

ParameterDescription
filenameThe name of the file to delete

int XDeleteDirectory(
  char *directoryName
)
Deletes a directory

ParameterDescription
directoryNameThe 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;

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

ParameterDescription
xcontrolA 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

ParameterDescription
padStateA pointer to a XPadState structure that will contain the current state
xcontrolThe pointer to the control structure
padNumberWhich 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!

ParameterDescription
padStateA pointer to a XPadState structure
xcontrolThe pointer to the control structure
padNumberWhich 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.

ParameterDescription
xcontrolThe pointer to the control structure



Back to Home Page