lhearachel/narc
1
Fork 0
mirror of https://github.com/lhearachel/narc.git synced 2025-06-18 13:35:32 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: Stash initial API contract target in README

Browse Source
This commit is contained in:
Rachel 2024-12-26 21:04:36 -08:00
parent cc0bf07f3f
commit 318a3249b8
1 changed files with 65 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
README.md
View File

@ -20,6 +20,71 @@ DS.
## API
```c
#include <stddef.h>
#include <stdint.h>
struct narc;
/*
* Allocate memory for a new NARC.
*/
struct narc *narc_alloc(void);
/*
* Free allocated NARC memory.
*/
void narc_free(struct narc *narc);
/*
* Load a NARC from an existing file on disk at the given path.
*/
int narc_load(struct narc *narc, const char *file_path);
/*
* Write a NARC to a file on disk at the given path.
*/
int narc_write(struct narc *narc, const char *file_path);
/*
* Add a file image to the end of a NARC. If successful, then `out_file_id` will
* be set to the file ID of the persisted image.
*/
int narc_add(struct narc *narc, unsigned char file_image[], uint16_t *out_file_id);
/*
* Read a file image with the given ID from a NARC. If such a file image exists,
* then `out_file_image` will be set to the in-memory address of the file image
* within the NARC and `out_file_size` will be set to the byte-size of that
* image.
*/
int narc_read(struct narc *narc, uint16_t file_id, unsigned char *out_file_image[], size_t *out_file_size);
/*
* Compute the SHA-1 hash of this NARC.
*
* The resulting hash will always be 20 bytes in length.
*/
uint8_t *narc_hash(struct narc *narc);
/*
* Compute the SHA-1 hash of a file image with the given ID within a NARC. If
* such a file exists, then `out_file_hash` will be set to the resulting 20-byte
* hash.
*/
int narc_hash_file(struct narc *narc, uint16_t file_id, uint8_t *out_file_hash[]);
/*
* Report the number of files contained within a NARC.
*/
uint16_t narc_num_files(struct narc *narc);
/*
* Print a report on internal information about a NARC. Useful for debugging.
*/
void narc_printf(struct narc *narc);
```
## Acknowledgements
- Martin Korth's [`gbatek` documentation][gbatek], which is an excellent read