Skip to content

Commit 3b80fe4

Browse files
committed
Update C API documentation
Function `sqlite3mc_cipher_name_copy` was added.
1 parent dc88b6f commit 3b80fe4

File tree

1 file changed

+27
-6
lines changed

1 file changed

+27
-6
lines changed

docs/configuration/config_capi.md

Lines changed: 27 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -27,12 +27,13 @@ The functions `sqlite3_key()`, `sqlite3_key_v2()`, `sqlite3_rekey()`, and `sqlit
2727

2828
## Registration functions
2929

30-
| Function | Description |
31-
| :--- | :--- |
32-
| [`sqlite3mc_register_cipher()`](#cipher_register) | Register a cipher scheme |
33-
| [`sqlite3mc_cipher_count()`](#cipher_count) | Retrieve number of registered cipher schemes |
34-
| [`sqlite3mc_cipher_index()`](#cipher_index) | Retrieve index of a cipher scheme |
35-
| [`sqlite3mc_cipher_name()`](#cipher_name) | Retrieve name of cipher at a given index |
30+
| Function | Description | Remarks |
31+
| :--- | :--- | :--- |
32+
| [`sqlite3mc_register_cipher()`](#cipher_register) | Register a cipher scheme | |
33+
| [`sqlite3mc_cipher_count()`](#cipher_count) | Retrieve number of registered cipher schemes | |
34+
| [`sqlite3mc_cipher_index()`](#cipher_index) | Retrieve index of a cipher scheme | |
35+
| [`sqlite3mc_cipher_name()`](#cipher_name) | Retrieve name of cipher at a given index | **Deprecated**, not thread-safe |
36+
| [`sqlite3mc_cipher_name_copy()`](#cipher_name_copy) | Retrieve a copy of the cipher name at a given index | |
3637

3738
---
3839

@@ -274,6 +275,26 @@ Notes
274275
{: .label .label-red .ml-0 .mb-1 .mt-2 }
275276
- An empty string is returned if an invalid index was given.
276277
- The returned string is valid until the next call to this function. That is, the string will be overwritten by the next call to this function.
278+
- The function is **not thread-safe**, and was therefore **deprecated**. It should not be used in new code any longer. Instead use [`sqlite3mc_cipher_name_copy()`](#cipher_name_copy).
279+
280+
## <a name="cipher_name_copy" />Function `sqlite3mc_cipher_name_copy()`
281+
282+
```c
283+
SQLITE_API int sqlite3mc_cipher_name_copy(
284+
int cipherIndex /* Index of cipher scheme */
285+
char* cipherName /* Buffer for name of cipher scheme */
286+
int maxCipherNameSize /* Size of the cipher name buffer */
287+
);
288+
```
289+
290+
`sqlite3mc_cipher_name_copy()` retrieves a copy of the name of the cipher scheme for the given relative 1-based index in the list of registered cipher schemes in a caller-provided buffer.
291+
292+
Notes
293+
{: .label .label-red .ml-0 .mb-1 .mt-2 }
294+
- The function returns a status code:
295+
- `1` : The name of the cipher scheme was sucessfully retrieved
296+
- `0` : The index of the cipher scheme was invalid (out of range)
297+
- `-n`: The provided buffer was too small, the required buffer size is at least `n` characters
277298

278299
## <a name="cipher_register" />Function `sqlite3mc_register_cipher()`
279300

0 commit comments

Comments
 (0)