Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

31    Patch

System Management

Exploring Palm OS®

This chapter describes APIs that you use to create patches to augment or replace one or more shared library functions. The material in this chapter is organized into the following sections:

Patch Structures and Types
Patch Constants

The header file Patch.h declares the API that this chapter describes.

For instructions on using these APIs to patch a shared library, see Chapter 6, "Shared Libraries."

Patch Structures and Types ^TOP^

SysPatchEntryNumType Typedef ^TOP^

Purpose

Container for a shared library vector table entry number.

Declared In

Patch.h

Prototype

typedef uint32_t SysPatchEntryNumType

Comments

The SysPatchTargetHeaderType structure is followed by one or more values of this type, indicating the shared library functions that are being patched.

SysPatchTargetHeaderType Struct ^TOP^

Purpose

Patch header, identifying the shared library being patched and the number of entry points in that shared library that are being patched.

Declared In

Patch.h

Prototype

typedef struct SysPatchTargetHeaderType {
   uint32_t type;
   uint32_t creator;
   uint16_t rsrcID;
   uint16_t flags;
   uint32_t numEntries;
} SysPatchTargetHeaderType

Fields

type
Type of the shared library to patch.
creator
Creator ID of the shared library to patch.
rsrcID
Resource ID of the shared library to patch.
flags
Zero—indicating that the patch can occur at any position within the patch call chain—or one of the Patch Flags to request that the patch be placed at the head or the tail of the patch call chain.
numEntries
Total number of entry points being patched.

Comments

This structure should be followed immediately by one or more SysPatchEntryNumType values (the number of values is specified in the SysPatchTargetHeaderType structure's numEntries field). Each value is an entry number in the shared library's vector table and indicates a function that is being patched. The order in which these vector table entry numbers occur must match the patch's exports as defined in the patch's Shared Library Definition (SLD) file, and the values must appear in the order of increasing entry numbers.

Patch Constants ^TOP^

Patch Flags ^TOP^

Purpose

Indicate how the patch should be inserted into the patch chain.

Declared In

Patch.h

Constants

#define patchFlagHead ((uint16_t)0x0001)
The patch should be placed at the head of the patch call chain.
#define patchFlagTail ((uint16_t)0x0002)
The patch should be placed at the tail of the patch call chain.

Comments

Note that just because you request that a patch be placed at the head or tail of the patch call chain, there is no guarantee that your patch will actually be placed there. The operating system provides no mechanism to arbitrate between two patches that patch the same shared library function and that both need to be at the head or tail of the patch call chain.

Miscellaneous Patch Constants ^TOP^

Purpose

Patch.h also defines the following constants.

Declared In

Patch.h

Constants

#define patchFlagReservedMask ((uint16_t)0xfffc)
A mask that isolates those SysPatchTargetHeaderType flags that are reserved for system use.