44 lines
3.0 KiB
Markdown
44 lines
3.0 KiB
Markdown
# `chd-capi`
|
|
|
|
⚠️*The C API has not been heavily tested. Use at your own risk.* ⚠️
|
|
|
|
chd-rs provides a C API compatible with [chd.h](https://github.com/rtissera/libchdr/blob/6eeb6abc4adc094d489c8ba8cafdcff9ff61251b/include/libchdr/chd.h).
|
|
ABI compatibility is detailed below but is untested when compiling as a dynamic library. The intended consumption for this crate is not via cargo, but by vendoring
|
|
the [sources of the C API](https://github.com/SnowflakePowered/chd-rs/tree/master/chd-rs-capi) in tree, along with a compatible `libchdcorefile` implementation
|
|
for your platform.
|
|
|
|
## Features
|
|
### `verify_block_crc`
|
|
Enables the `verify_block_crc` of the `chd` crate to verify decompressed CHD hunks with their internal hash.
|
|
|
|
### `chd_core_file`
|
|
Enables `core_file*` and the`chd_open_file`, and `chd_core_file` APIs. This feature requires a `libchdcorefile` implementation,
|
|
or the default POSIX compatible implementation (where `core_file*` is `FILE*`) will be used.
|
|
|
|
Note that by default, `core_file*` is not an opaque pointer and is a C `FILE*` stream. This allows the underlying
|
|
file pointer to be changed unsafely beneath the memory safety guarantees of chd-rs. We strongly encourage using
|
|
`chd_open` instead of `chd_open_file`.
|
|
|
|
If you need `core_file*` support, chd-capi should have the `chd_core_file` feature enabled, which will wrap
|
|
`FILE*` to be usable in Rust with a lightweight wrapper in `libchdcorefile`. If the default implementation
|
|
is not suitable, you may need to implement `libchdcorefile` yourself. The `chd_core_file` feature requires
|
|
CMake and Clang to be installed.
|
|
|
|
### `chd_virtio`
|
|
Enables the [virtual I/O](https://github.com/rtissera/libchdr/pull/78) functions `chd_open_core_file`.
|
|
Because this C API requires `core_file` to be an opaque pointer, there is no difference between `chd_open_file` and
|
|
`chd_open_core_file` unlike libchdr, and `chd_open_core_file` is simply an alias for `chd_open_file`. All functions that
|
|
take `core_file*` require a `libchdcorefile` implementation.
|
|
|
|
### `chd_precache`
|
|
Enables precaching of the underlying file into memory with the `chd_precache_progress` and `chd_precache` functions.
|
|
|
|
## ABI compatibility
|
|
|
|
chd-rs makes the following ABI-compatibility guarantees compared to libchdr when compiled statically.
|
|
* `chd_error` is ABI and API-compatible with [chd.h](https://github.com/rtissera/libchdr/blob/cdcb714235b9ff7d207b703260706a364282b063/include/libchdr/chd.h#L258)
|
|
* `chd_header` is ABI and API-compatible [chd.h](https://github.com/rtissera/libchdr/blob/cdcb714235b9ff7d207b703260706a364282b063/include/libchdr/chd.h#L302)
|
|
* `chd_file *` is an opaque pointer. It is **not layout compatible** with [chd.c](https://github.com/rtissera/libchdr/blob/cdcb714235b9ff7d207b703260706a364282b063/src/libchdr_chd.c#L265)
|
|
* The layout of `core_file *` is user-defined when the `chd_core_file` feature is enabled.
|
|
* Freeing any pointer returned by chd-rs with `free` is undefined behaviour. The exception are `chd_file *` pointers which can be safely freed with `chd_close`.
|