docs
Loading...
Searching...
No Matches
CAPI_Buffer.h
Go to the documentation of this file.
1///
2/// Copyright (C) 2026 Ultralight, Inc. All rights reserved.
3/// A license is required for commercial use. https://ultralig.ht
4///
5
6///
7/// @file CAPI_Buffer.h
8///
9/// A fixed-size container for raw byte data.
10///
11/// `#include <Ultralight/CAPI/CAPI_Buffer.h>`
12///
13/// ULBuffer is an opaque handle representing a raw data buffer in Ultralight. It intelligently
14/// manages the lifetime of the data and can optionally call a user-supplied callback to deallocate
15/// the data when the Buffer is destroyed.
16///
17#ifndef ULTRALIGHT_CAPI_BUFFER_H
18#define ULTRALIGHT_CAPI_BUFFER_H
19
21
22#ifdef __cplusplus
23extern "C" {
24#endif
25
26///
27/// Callback invoked when a Buffer created via ulCreateBuffer() is destroyed.
28/// Use this to deallocate any user-managed data associated with the Buffer.
29///
30/// @param user_data The user data pointer that was passed to ulCreateBuffer().
31///
32/// @param data The raw data pointer that was passed to ulCreateBuffer().
33///
34typedef void (*ulDestroyBufferCallback)(void* user_data, void* data);
35
36///
37/// Create a Buffer from existing, user-owned data without any copies. An optional, user-supplied
38/// callback will be called to deallocate data upon destruction.
39///
40/// @param data A pointer to the data.
41///
42/// @param size Size of the data in bytes.
43///
44/// @param user_data Optional user data that will be passed to destruction_callback
45/// when the returned Buffer is destroyed.
46///
47/// @param destruction_callback Optional callback that will be called upon destruction. Pass a
48/// null pointer if you don't want to be informed of destruction.
49///
50/// @return A new ULBuffer instance. You must call ulDestroyBuffer() when finished.
51///
52ULExport ULBuffer ulCreateBuffer(void* data, size_t size, void* user_data,
53 ulDestroyBufferCallback destruction_callback);
54
55///
56/// Create a Buffer from existing data, a deep copy of data will be made.
57///
58/// @param data A pointer to the data to copy.
59///
60/// @param size Size of the data in bytes.
61///
62/// @return A new ULBuffer instance. You must call ulDestroyBuffer() when finished.
63///
64ULExport ULBuffer ulCreateBufferFromCopy(const void* data, size_t size);
65
66///
67/// Create another owned reference to an existing Buffer (no data is copied).
68///
69/// You can use this to keep a buffer that was passed to you as a borrowed handle beyond the call
70/// that provided it.
71///
72/// @param buffer The buffer to reference.
73///
74/// @return Returns a new owned reference to the same Buffer. You must call ulDestroyBuffer() when
75/// finished.
76///
78
79///
80/// Destroy a buffer previously created with ulCreateBuffer(), ulCreateBufferFromCopy(), or
81/// ulCreateBufferRef().
82///
83/// @param buffer The buffer to destroy.
84///
86
87///
88/// Get a pointer to the raw byte data.
89///
91
92///
93/// Get the size in bytes.
94///
96
97///
98/// Get the user data associated with this Buffer, if any.
99///
101
102///
103/// Check whether this Buffer owns its own data (Buffer was created via ulCreateBufferFromCopy).
104/// If this is false, Buffer will call the user-supplied destruction callback to deallocate data
105/// when this Buffer instance is destroyed.
106///
108
109#ifdef __cplusplus
110} // extern "C"
111#endif
112
113#endif // ULTRALIGHT_CAPI_BUFFER_H
bool ulBufferOwnsData(ULBuffer buffer)
Check whether this Buffer owns its own data (Buffer was created via ulCreateBufferFromCopy).
void(*) ulDestroyBufferCallback(void *user_data, void *data)
Callback invoked when a Buffer created via ulCreateBuffer() is destroyed.
Definition CAPI_Buffer.h:34
void * ulBufferGetData(ULBuffer buffer)
Get a pointer to the raw byte data.
size_t ulBufferGetSize(ULBuffer buffer)
Get the size in bytes.
void ulDestroyBuffer(ULBuffer buffer)
Destroy a buffer previously created with ulCreateBuffer(), ulCreateBufferFromCopy(),...
ULBuffer ulCreateBufferRef(ULBuffer buffer)
Create another owned reference to an existing Buffer (no data is copied).
void * ulBufferGetUserData(ULBuffer buffer)
Get the user data associated with this Buffer, if any.
ULBuffer ulCreateBufferFromCopy(const void *data, size_t size)
Create a Buffer from existing data, a deep copy of data will be made.
ULBuffer ulCreateBuffer(void *data, size_t size, void *user_data, ulDestroyBufferCallback destruction_callback)
Create a Buffer from existing, user-owned data without any copies.
Various defines and utility functions for the C API.
#define ULExport
Definition CAPI_Defines.h:42
struct C_Buffer * ULBuffer
Opaque handle to a Buffer object.
Definition CAPI_Defines.h:99