Zydis  v3.1.0
FormatterBuffer.h File Reference

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

#include <ZydisExportConfig.h>
#include <Zycore/String.h>
#include <Zycore/Types.h>
#include <Zydis/Status.h>
Include dependency graph for FormatterBuffer.h:
This graph shows which files directly or indirectly include this file:

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

Typedefs

typedef ZyanU8 ZydisTokenType
 @biref Defines the ZydisTokenType data-type. More...
 
typedef struct ZydisFormatterToken_ ZydisFormatterToken
 Defines the ZydisFormatterToken struct. More...
 
typedef const ZydisFormatterToken ZydisFormatterTokenConst
 Defines the ZydisFormatterTokenConst data-type. More...
 
typedef struct ZydisFormatterBuffer_ ZydisFormatterBuffer
 Defines the ZydisFormatterBuffer struct. More...
 

Functions

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

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

Defines the ZydisFormatterBuffer struct.

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

◆ ZydisFormatterToken

Defines the ZydisFormatterToken struct.

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

◆ ZydisFormatterTokenConst

Defines the ZydisFormatterTokenConst data-type.

◆ ZydisTokenType

typedef ZyanU8 ZydisTokenType

@biref Defines the ZydisTokenType data-type.

Function Documentation

◆ ZydisFormatterBufferAppend()

ZYDIS_EXPORT ZyanStatus ZydisFormatterBufferAppend ( ZydisFormatterBuffer buffer,
ZydisTokenType  type 
)

Appends a new token to the buffer.

Parameters
bufferA pointer to the ZydisFormatterBuffer struct.
typeThe 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
bufferA pointer to the ZydisFormatterBuffer struct.
stringReceives 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
bufferA pointer to the ZydisFormatterBuffer struct.
tokenReceives 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
bufferA pointer to the ZydisFormatterBuffer struct.
stateReceives 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
bufferA pointer to the ZydisFormatterBuffer struct.
stateThe 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
tokenA pointer to the ZydisFormatterToken struct.
typeReceives the token type.
valueReceives 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
tokenReceives a pointer to the next ZydisFormatterToken struct linked to the passed one.
Returns
A zyan status code.