Zydis: include/Zydis/FormatterBuffer.h File Reference

Zydis v4.1.1

Loading...
Searching...
No Matches
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.