Zydis: include/Zydis/FormatterBuffer.h File Reference

Zydis v4.1.0

Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Functions
FormatterBuffer.h File Reference

Implements the `ZydisFormatterToken` type and provides functions to use it. More...

`#include <Zycore/String.h>`
`#include <Zycore/Types.h>`
`#include <Zydis/Defines.h>`
`#include <Zydis/Status.h>`

Go to the source code of this file.

## Data Structures
struct | ZydisFormatterToken_
| Defines the `ZydisFormatterToken` struct. More...
struct | ZydisFormatterBuffer_
| Defines the `ZydisFormatterBuffer` struct. More...

## Macros
#define | ZYDIS_TOKEN_INVALID 0x00
#define | ZYDIS_TOKEN_WHITESPACE 0x01
| A whitespace character.
#define | ZYDIS_TOKEN_DELIMITER 0x02
| A delimiter character (like ‘’,'`,`':'`,`'+'`,`'-'`,`'*'`).
#define | ZYDIS_TOKEN_PARENTHESIS_OPEN 0x03
| An opening parenthesis character (like ‘’('`,`'['`,`'{'`).
#define | ZYDIS_TOKEN_PARENTHESIS_CLOSE 0x04
| A closing parenthesis character (like ‘’)'`,`']'`,`'}'`).
#define | ZYDIS_TOKEN_PREFIX 0x05
| A prefix literal (like `"LOCK"`, `"REP"`).
#define | ZYDIS_TOKEN_MNEMONIC 0x06
| A mnemonic literal (like `"MOV"`, `"VCMPPSD"`, `"LCALL"`).
#define | ZYDIS_TOKEN_REGISTER 0x07
| A register literal (like `"RAX"`, `"DS"`, `"%ECX"`).
#define | ZYDIS_TOKEN_ADDRESS_ABS 0x08
| An absolute address literal (like `0x00400000`).
#define | ZYDIS_TOKEN_ADDRESS_REL 0x09
| A relative address literal (like `-0x100`).
#define | ZYDIS_TOKEN_DISPLACEMENT 0x0A
| A displacement literal (like `0xFFFFFFFF`, `-0x100`, `+0x1234`).
#define | ZYDIS_TOKEN_IMMEDIATE 0x0B
| An immediate literal (like `0xC0`, `-0x1234`, `$0x0000`).
#define | ZYDIS_TOKEN_TYPECAST 0x0C
| A typecast literal (like `DWORD PTR`).
#define | ZYDIS_TOKEN_DECORATOR 0x0D
| A decorator literal (like `"Z"`, `"1TO4"`).
#define | ZYDIS_TOKEN_SYMBOL 0x0E
| A symbol literal.
#define | ZYDIS_TOKEN_USER 0x80
| The base for user-defined token types.

## Typedefs
typedef ZyanU8 | ZydisTokenType
| Defines the `ZydisTokenType` data-type.
typedef struct ZydisFormatterToken_ | ZydisFormatterToken
| Defines the `ZydisFormatterToken` struct.
typedef const ZydisFormatterToken | ZydisFormatterTokenConst
| Defines the `ZydisFormatterTokenConst` data-type.
typedef struct ZydisFormatterBuffer_ | ZydisFormatterBuffer
| Defines the `ZydisFormatterBuffer` struct.

## Functions
ZYDIS_EXPORT ZyanStatus | ZydisFormatterTokenGetValue (const ZydisFormatterToken *token, ZydisTokenType *type, ZyanConstCharPointer *value)
| Returns the `type` and the string `value` of the given `token`.
ZYDIS_EXPORT ZyanStatus | ZydisFormatterTokenNext (ZydisFormatterTokenConst **token)
| Obtains the next `token` linked to the passed one.
ZYDIS_EXPORT ZyanStatus | ZydisFormatterBufferGetToken (const ZydisFormatterBuffer *buffer, ZydisFormatterTokenConst **token)
| Returns the current (most recently added) token.
ZYDIS_EXPORT ZyanStatus | ZydisFormatterBufferGetString (ZydisFormatterBuffer *buffer, ZyanString **string)
| Returns the `ZyanString` instance associated with the given buffer.
ZYDIS_EXPORT ZyanStatus | ZydisFormatterBufferAppend (ZydisFormatterBuffer *buffer, ZydisTokenType type)
| Appends a new token to the `buffer`.
ZYDIS_EXPORT ZyanStatus | ZydisFormatterBufferRemember (const ZydisFormatterBuffer *buffer, ZyanUPointer *state)
| Returns a snapshot of the buffer-state.
ZYDIS_EXPORT ZyanStatus | ZydisFormatterBufferRestore (ZydisFormatterBuffer *buffer, ZyanUPointer state)
| Restores a previously saved buffer-state.

## Detailed Description

Implements the `ZydisFormatterToken` type and provides functions to use it.

## Macro Definition Documentation

## ◆ ZYDIS_TOKEN_ADDRESS_ABS

#define ZYDIS_TOKEN_ADDRESS_ABS 0x08

An absolute address literal (like `0x00400000`).

## ◆ ZYDIS_TOKEN_ADDRESS_REL

#define ZYDIS_TOKEN_ADDRESS_REL 0x09

A relative address literal (like `-0x100`).

## ◆ ZYDIS_TOKEN_DECORATOR

#define ZYDIS_TOKEN_DECORATOR 0x0D

A decorator literal (like `"Z"`, `"1TO4"`).

## ◆ ZYDIS_TOKEN_DELIMITER

#define ZYDIS_TOKEN_DELIMITER 0x02

A delimiter character (like ‘’,'`,`':'`,`'+'`,`'-'`,`'*'`).

## ◆ ZYDIS_TOKEN_DISPLACEMENT

#define ZYDIS_TOKEN_DISPLACEMENT 0x0A

A displacement literal (like `0xFFFFFFFF`, `-0x100`, `+0x1234`).

## ◆ ZYDIS_TOKEN_IMMEDIATE

#define ZYDIS_TOKEN_IMMEDIATE 0x0B

An immediate literal (like `0xC0`, `-0x1234`, `$0x0000`).

## ◆ ZYDIS_TOKEN_INVALID

#define ZYDIS_TOKEN_INVALID 0x00

## ◆ ZYDIS_TOKEN_MNEMONIC

#define ZYDIS_TOKEN_MNEMONIC 0x06

A mnemonic literal (like `"MOV"`, `"VCMPPSD"`, `"LCALL"`).

## ◆ ZYDIS_TOKEN_PARENTHESIS_CLOSE

#define ZYDIS_TOKEN_PARENTHESIS_CLOSE 0x04

A closing parenthesis character (like ‘’)'`,`']'`,`'}'`).

## ◆ ZYDIS_TOKEN_PARENTHESIS_OPEN

#define ZYDIS_TOKEN_PARENTHESIS_OPEN 0x03

An opening parenthesis character (like ‘’('`,`'['`,`'{'`).

## ◆ ZYDIS_TOKEN_PREFIX

#define ZYDIS_TOKEN_PREFIX 0x05

A prefix literal (like `"LOCK"`, `"REP"`).

## ◆ ZYDIS_TOKEN_REGISTER

#define ZYDIS_TOKEN_REGISTER 0x07

A register literal (like `"RAX"`, `"DS"`, `"%ECX"`).

## ◆ ZYDIS_TOKEN_SYMBOL

#define ZYDIS_TOKEN_SYMBOL 0x0E

A symbol literal.

## ◆ ZYDIS_TOKEN_TYPECAST

#define ZYDIS_TOKEN_TYPECAST 0x0C

A typecast literal (like `DWORD PTR`).

## ◆ ZYDIS_TOKEN_USER

#define ZYDIS_TOKEN_USER 0x80

The base for user-defined token types.

## ◆ ZYDIS_TOKEN_WHITESPACE

#define ZYDIS_TOKEN_WHITESPACE 0x01

A whitespace character.

## Typedef Documentation

## ◆ ZydisFormatterBuffer

typedef struct ZydisFormatterBuffer_ ZydisFormatterBuffer

Defines the `ZydisFormatterBuffer` struct.

All fields in this struct should be considered as "private". Any changes may lead to unexpected behavior.

## ◆ ZydisFormatterToken

typedef struct ZydisFormatterToken_ ZydisFormatterToken

Defines the `ZydisFormatterToken` struct.

All fields in this struct should be considered as "private". Any changes may lead to unexpected behavior.

## ◆ ZydisFormatterTokenConst

typedef const ZydisFormatterToken ZydisFormatterTokenConst

Defines the `ZydisFormatterTokenConst` data-type.

## ◆ ZydisTokenType

typedef ZyanU8 ZydisTokenType

Defines the `ZydisTokenType` data-type.

## Function Documentation

## ◆ ZydisFormatterBufferAppend()

ZYDIS_EXPORT ZyanStatus ZydisFormatterBufferAppend | ( | ZydisFormatterBuffer * | buffer,
|  | ZydisTokenType | type )

Appends a new token to the `buffer`.

Parameters

  buffer | A pointer to the `ZydisFormatterBuffer` struct.
  type | The type of the new token.

Returns
  A zyan status code.

Note that the `ZyanString` instance returned by `ZydisFormatterBufferGetString` will automatically be updated by calling this function.

## ◆ ZydisFormatterBufferGetString()

ZYDIS_EXPORT ZyanStatus ZydisFormatterBufferGetString | ( | ZydisFormatterBuffer * | buffer,
|  | ZyanString ** | string )

Returns the `ZyanString` instance associated with the given buffer.

Parameters

  buffer | A pointer to the `ZydisFormatterBuffer` struct.
  string | Receives a pointer to the `ZyanString` instance associated with the given buffer.

Returns
  A zyan status code.

This function returns `ZYAN_STATUS_INVALID_OPERATION`, if the buffer does not contain at least one token.

The returned string always refers to the literal value of the current (most recently added) token and will remain valid until the buffer is destroyed.

## ◆ ZydisFormatterBufferGetToken()

ZYDIS_EXPORT ZyanStatus ZydisFormatterBufferGetToken | ( | const ZydisFormatterBuffer * | buffer,
|  | ZydisFormatterTokenConst ** | token )

Returns the current (most recently added) token.

Parameters

  buffer | A pointer to the `ZydisFormatterBuffer` struct.
  token | Receives a pointer to the current token.

Returns
  A zyan status code.

This function returns `ZYAN_STATUS_INVALID_OPERATION`, if the buffer does not contain at least one token.

## ◆ ZydisFormatterBufferRemember()

ZYDIS_EXPORT ZyanStatus ZydisFormatterBufferRemember | ( | const ZydisFormatterBuffer * | buffer,
|  | ZyanUPointer * | state )

Returns a snapshot of the buffer-state.

Parameters

  buffer | A pointer to the `ZydisFormatterBuffer` struct.
  state | Receives a snapshot of the buffer-state.

Returns
  A zyan status code.

Note that the buffer-state is saved inside the buffer itself and thus becomes invalid as soon as the buffer gets overwritten or destroyed.

## ◆ ZydisFormatterBufferRestore()

ZYDIS_EXPORT ZyanStatus ZydisFormatterBufferRestore | ( | ZydisFormatterBuffer * | buffer,
|  | ZyanUPointer | state )

Restores a previously saved buffer-state.

Parameters

  buffer | A pointer to the `ZydisFormatterBuffer` struct.
  state | The buffer-state to restore.

Returns
  A zyan status code.

All tokens added after obtaining the given `state` snapshot will be removed. This function does NOT restore any string content.

Note that the `ZyanString` instance returned by `ZydisFormatterBufferGetString` will automatically be updated by calling this function.

## ◆ ZydisFormatterTokenGetValue()

ZYDIS_EXPORT ZyanStatus ZydisFormatterTokenGetValue | ( | const ZydisFormatterToken * | token,
|  | ZydisTokenType * | type,
|  | ZyanConstCharPointer * | value )

Returns the `type` and the string `value` of the given `token`.

Parameters

  token | A pointer to the `ZydisFormatterToken` struct.
  type | Receives the token type.
  value | Receives a pointer to the string value of the token.

Returns
  A zyan status code.

## ◆ ZydisFormatterTokenNext()

ZYDIS_EXPORT ZyanStatus ZydisFormatterTokenNext | ( | ZydisFormatterTokenConst ** | token | ) |

Obtains the next `token` linked to the passed one.

Parameters

  token | Receives a pointer to the next `ZydisFormatterToken` struct linked to the passed one.

Returns
  A zyan status code.