In this header the general access to the library can be found.

The wrapper class declared in [`callstack.hpp`][1] is automatically included by this header when compiled using a 
C++ compiler.

### `struct callstack`
The structure of a callstack. It consists of the translation status, the backtrace and the
translated callstack frames.

#### [`enum callstack_type`][2] `translationStatus`
The translation status to be human-readable.

#### `size_t` `frameCount`
The amount of available translated callstack frames.

> [!NOTE]
> Added in version **1.1**.

#### [`struct callstack_frame *`][3] `frames`
An array of translated [callstack frames][3].

> [!NOTE]
> Added in version **1.1**.

#### `size_t` `backtraceSize`
The amount of traced callstack frames.

#### `void *` `backtrace[`[`CALLSTACK_BACKTRACE_SIZE`][4]`]`
The actual backtrace. Can contain as much as [`CALLSTACK_BACKTRACE_SIZE`][4] frames at maximum.

### [`struct callstack *`][6] `callstack_new(void)`
Creates a callstack of the calling function. The backtrace of the calling function is created.
The `struct` is allocated and needs to be freed using the function [`callstack_delete(struct callstack *)`][5].
In case of an error, `NULL` is returned.

### [`struct callstack *`][6] `callstack_newWithAddress(void *)`
Creates a callstack of the calling function, ignoring all frames after the given stack address.
The `struct` is allocated and needs to be freed using the function [`callstack_delete(struct callstack *)`][5].
In case of an error, `NULL` is returned.

### `bool` `callstack_emplace(`[`struct callstack *`][6]`)`
Constructs the given callstack object. Stores the backtrace of the calling function. The callstack object
needs to be destructed using the function [`callstack_destroy(struct callstack *)`][7] after use.  
Returns `false` if an error occurred during the initialization of the given callstack object.

### `bool` `callstack_emplaceWithAddress(`[`struct callstack *`][6]`, void *)`
Constructs the given callstack object. Stores the backtrace of the calling function, ignoring
all frames after the given stack address. The callstack object needs to be destructed using the function
[`callstack_destroy(struct callstack *)`][7] upon successful construction and use.

### `bool` `callstack_emplaceWithBacktrace(`[`struct callstack *`][6]`, void *[], int)`
Constructs the given callstack object. Copies the given callstack into the given object. If the trace
is longer than [`CALLSTACK_BACKTRACE_SIZE`][4], only the first addresses are copied. The callstack object needs to be
destructed using the function [`callstack_destroy(struct callstack *)`][7] after use.  
If the given trace's length is smaller than `0` `false` is returned and the given callstack object is not modified.

### `void` `callstack_copy(`[`struct callstack *`][6]`, `[`const struct callstack *`][6]`)`
Copies the given callstack. The given callstack is destroyed before the contents of the other one copied.

### `bool` `callstack_relativize(`[`struct callstack*`][6]`, const char**)`
Relativizes the given callstack object.  
Upon successful return of the function, the addresses within the callstack object have become offsets into the runtime
image they belong to. The names of these runtime images are stored within the given string array. This string array
therefor should be capable to hold at least the same amount of strings as the amount of entries within the given
callstack object.

> [!NOTE]
> Added in version **2.3**.

### [`struct callstack_frame *`][3] `callstack_translateRelative(`[`struct callstack *`][6]`, const char**)`
Translates the given relativized callstack object using the provided array of binary file names.  
The given string array must hold at least the same amount of binary file names as the amount of entries within the given
callstack object.  
Returns an array of the translated callstack frames.

> [!NOTE]
> Added in version **2.3**.

### [`struct callstack_frame *`][3] `callstack_toArray(`[`struct callstack *`][6]`)`
Translates the given callstack and returns an array of the translated frames.

> [!NOTE]
> Since version **1.1** a callstack frame array is returned.
> 
> Previously a string array was returned.

Returns `NULL` if an error happens.

### [`struct callstack_frame *`][3] `callstack_getBinaries(`[`struct callstack *`][6]`)`
Translates the given callstack and returns an array of the translated frames. If the given callstack has not been
translated before, only the binary file information is deducted.

Returns `NULL` if an error happens.

### `size_t` `callstack_getFrameCount(`[`struct callstack *`][6]`)`
Returns the number of frames stored in the given callstack.

### [`enum callstack_type`][2] `callstack_getType(`[`struct callstack *`][6]`)`
Returns the type of the given callstack. See [callstack_type.h][8] for more information about the possible values.

### `bool` `callstack_isTranslated(`[`struct callstack *`][6]`)`
Returns whether the given callstack is already translated.

### `void` `callstack_destroy(`[`struct callstack *`][6]`)`
Destroys the contents of the given callstack object.

### `void` `callstack_delete(`[`struct callstack *`][6]`)`
Destroys and deallocates the given callstack object.

[1]: https://github.com/mhahnFr/CallstackLibrary/wiki/callstack.hpp
[2]: https://github.com/mhahnFr/CallstackLibrary/wiki/callstack_type.h#enum-callstack_type
[3]: https://github.com/mhahnFr/CallstackLibrary/wiki/callstack_frame.h#struct-callstack_frame
[4]: https://github.com/mhahnFr/CallstackLibrary/wiki/callstack_defs.h#CALLSTACK_BACKTRACE_SIZE
[5]: #void-callstack_deletestruct-callstack-6
[6]: #struct-callstack
[7]: #void-callstack_destroystruct-callstack-6
[8]: https://github.com/mhahnFr/CallstackLibrary/wiki/callstack_type.h