**This is currently a work-in-progress.** This document aims to provide you an overview of how to port your Matrix application from libolm to vodozemac. = Definitions = We will be using the following definitions in the document: - The **E2EE library** means either libolm or vodozemac. - The **application** means any code that uses the E2EE library, which may be another library. - The **user** means anyone who interacts with the application in any way other than writing code. = Differences = [[ https://lily-is.land/kazv/vodozemac-bindings | vodozemac-bindings ]] has a C++ public API, as opposed to the C API of libolm. There are a couple of differences in the API: - Memory allocations are managed by vodozemac, not by the application. - You can no longer pass random data into the E2EE library, as vodozemac embeds the rust's random generator in it. This renders the [[https://spec.matrix.org/v1.11/appendices/#cryptographic-test-vectors | "test vectors"]] in the spec effectively useless. - You have to have exceptions support in your compiler. This is a limitation of cxx.rs , which is used to generate the bindings. See https://github.com/dtolnay/cxx/issues/1052 for more information. This might change later. = Overview of vodozemac-bindings =

**This is currently a work-in-progress.** This document aims to provide you an overview of how to port your Matrix application from libolm to vodozemac. = Definitions = We will be using the following definitions in the document: - The **E2EE library** means either libolm or vodozemac. - The **application** means any code that uses the E2EE library, which may be another library. - The **user** means anyone who interacts with the application in any way other than writing code. = Differences = [[ https://lily-is.land/kazv/vodozemac-bindings | vodozemac-bindings ]] has a C++ public API, as opposed to the C API of libolm. There are a couple of differences in the API: - Memory allocations are managed by vodozemac, not by the application. - You can no longer pass random data into the E2EE library, as vodozemac embeds the rust's random generator in it. This renders the [[https://spec.matrix.org/v1.11/appendices/#cryptographic-test-vectors | "test vectors"]] in the spec effectively useless. - You have to have exceptions support in your compiler. This is a limitation of cxx.rs , which is used to generate the bindings. See https://github.com/dtolnay/cxx/issues/1052 for more information. This might change later. - Pickle keys are now 32 bytes, instead of any string. = Overview of vodozemac-bindings = Everything is in the `vodozemac` namespace. A function may throw an exception if it returns anything other than `Result<T>` in rust code. In the generated C++ header, it corresponds to the `noexcept` specifier. If a function is declared `noexcept`, it does not throw an exception; otherwise, it may. You can use the following code to check for exceptions: ``` template<class Func> auto checkVodozemacError(Func &&func) -> std::optional<std::invoke_result_t<Func>> { try { return std::forward<Func>(func)(); } catch (const std::exception &e) { return std::nullopt; } } ``` = Converting from libolm = vodozemac-bindings provides function to convert data from libolm pickle format. They are called `*_from_libolm_pickle` and takes two arguments: the first one is the pickle data, as `rust::Str`, the other being the pickle key, as `rust::Slice<const unsigned char>`. `rust::Str` can be directly converted from a `std::string`, while `rust::Slice` needs some work, for example: ``` auto session = checkVodozemacError([&]() { }); ``` = Sample code = The commits referenced in https://iron.lily-is.land/T125 provides a sample code to migrate from libolm to vodozemac.

**This is currently a work-in-progress.** This document aims to provide you an overview of how to port your Matrix application from libolm to vodozemac. = Definitions = We will be using the following definitions in the document: - The **E2EE library** means either libolm or vodozemac. - The **application** means any code that uses the E2EE library, which may be another library. - The **user** means anyone who interacts with the application in any way other than writing code. = Differences = [[ https://lily-is.land/kazv/vodozemac-bindings | vodozemac-bindings ]] has a C++ public API, as opposed to the C API of libolm. There are a couple of differences in the API: - Memory allocations are managed by vodozemac, not by the application. - You can no longer pass random data into the E2EE library, as vodozemac embeds the rust's random generator in it. This renders the [[https://spec.matrix.org/v1.11/appendices/#cryptographic-test-vectors | "test vectors"]] in the spec effectively useless. - You have to have exceptions support in your compiler. This is a limitation of cxx.rs , which is used to generate the bindings. See https://github.com/dtolnay/cxx/issues/1052 for more information. This might change later. - Pickle keys are now 32 bytes, instead of any string. = Overview of vodozemac-bindings = Everything is in the `vodozemac` namespace. A function may throw an exception if it returns anything other than `Result<T>` in rust code. In the generated C++ header, it corresponds to the `noexcept` specifier. If a function is declared `noexcept`, it does not throw an exception; otherwise, it may. You can use the following code to check for exceptions: ``` template<class Func> auto checkVodozemacError(Func &&func) -> std::optional<std::invoke_result_t<Func>> { try { return std::forward<Func>(func)(); } catch (const std::exception &e) { return std::nullopt; } } ``` = Converting from libolm = vodozemac-bindings provides function to convert data from libolm pickle format. They are called `*_from_libolm_pickle` and takes two arguments: the first one is the pickle data, as `rust::Str`, the other being the pickle key, as `rust::Slice<const unsigned char>`. `rust::Str` can be directly converted from a `std::string`, while `rust::Slice` needs some work, for example: ``` auto session = checkVodozemacError([&]() { }); ``` = Sample code = The commits referenced in https://iron.lily-is.land/T125 provides a sample code to migrate from libolm to vodozemac.