keystone/bindings/csharp/MIGRATION.md

Changes

Names

• The KeystoneNET namespace was renamed to Keystone.
• The Keystone and KeystoneEncoded classes were respectively renamed to Engine and EncodedData.
• The KeystoneArchitecture, KeystoneMode, KeystoneOptionType and KeystoneOptionValue enums had their names changed, dropping the Keystone prefix (ie: Architecture, Mode, ...). Furthermore, their members were renamed, dropping the KS_MODE_, KS_ARCH_, and KS_OPT_ prefixes.

The Engine class

• The Engine constructor no longer takes bool throwOnError. Instead, the public ThrowOnError property now has both a getter and a setter, making it possible to alter the error behavior after initialization.
• Errors are no longer reported as InvalidOperationException, but instead as KeystoneException, a custom class which stores the returned error code.
• An error encountered in the constructor or when setting ResolveSymbol will throw an exception, regardless of the value of ThrowOnError.
• AppendAssemble was renamed to Assemble, and no longer accepts ICollection<byte>. Instead it accepts a byte[] buffer and an int index, and writes much more efficiently into it. A new overload accepting a Stream has also been added.
• The out uint statements parameter has been replaced by an out int statementCount parameter. It will always be positive, but better integrates into the C# language.

Examples

Namespace

using KeystoneNET;

becomes

using Keystone;

Initialization

using (var ks = new Keystone(KeystoneArchitecture.KS_ARCH_X86,
                             KeystoneMode.KS_MODE_32,
                             throwOnError: false))
{
}

becomes

using (var ks = new Engine(Architecture.X86, Mode.X32)
                          { ThrowOnError = true })
{
}

Catching errors

try
{
    ks.SymbolResolver += Callback;
}
catch (InvalidOperationException e)
{
    Console.WriteLine(e);
}

becomes

try
{
    ks.SymbolResolver += Callback;
}
catch (KeystoneException e)
{
    Console.WriteLine(e);
}

Assembling data

var data = new List<byte>();

ks.AppendAssemble("add eax, eax", data);

becomes

var data = new byte[1024];

ks.Assemble("add eax, eax", data);

or

using (var ms = new MemoryStream())
{
    ks.Assemble("add eax, eax", ms);
}