docs
Docs
C++ API
C API
Search API
Ctrl K
2.0
2.0
latest
1.4
Ultralight C API
2.0.0
Toggle main menu visibility
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
20
#include <
Ultralight/CAPI/CAPI_Defines.h
>
21
22
#ifdef __cplusplus
23
extern
"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
///
34
typedef
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
///
52
ULExport
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
///
64
ULExport
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
///
77
ULExport
ULBuffer
ulCreateBufferRef
(
ULBuffer
buffer);
78
79
///
80
/// Destroy a buffer previously created with ulCreateBuffer(), ulCreateBufferFromCopy(), or
81
/// ulCreateBufferRef().
82
///
83
/// @param buffer The buffer to destroy.
84
///
85
ULExport
void
ulDestroyBuffer
(
ULBuffer
buffer);
86
87
///
88
/// Get a pointer to the raw byte data.
89
///
90
ULExport
void
*
ulBufferGetData
(
ULBuffer
buffer);
91
92
///
93
/// Get the size in bytes.
94
///
95
ULExport
size_t
ulBufferGetSize
(
ULBuffer
buffer);
96
97
///
98
/// Get the user data associated with this Buffer, if any.
99
///
100
ULExport
void
*
ulBufferGetUserData
(
ULBuffer
buffer);
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
///
107
ULExport
bool
ulBufferOwnsData
(
ULBuffer
buffer);
108
109
#ifdef __cplusplus
110
}
// extern "C"
111
#endif
112
113
#endif
// ULTRALIGHT_CAPI_BUFFER_H
ulBufferOwnsData
bool ulBufferOwnsData(ULBuffer buffer)
Check whether this Buffer owns its own data (Buffer was created via ulCreateBufferFromCopy).
ulDestroyBufferCallback
void(*) ulDestroyBufferCallback(void *user_data, void *data)
Callback invoked when a Buffer created via ulCreateBuffer() is destroyed.
Definition
CAPI_Buffer.h:34
ulBufferGetData
void * ulBufferGetData(ULBuffer buffer)
Get a pointer to the raw byte data.
ulBufferGetSize
size_t ulBufferGetSize(ULBuffer buffer)
Get the size in bytes.
ulDestroyBuffer
void ulDestroyBuffer(ULBuffer buffer)
Destroy a buffer previously created with ulCreateBuffer(), ulCreateBufferFromCopy(),...
ulCreateBufferRef
ULBuffer ulCreateBufferRef(ULBuffer buffer)
Create another owned reference to an existing Buffer (no data is copied).
ulBufferGetUserData
void * ulBufferGetUserData(ULBuffer buffer)
Get the user data associated with this Buffer, if any.
ulCreateBufferFromCopy
ULBuffer ulCreateBufferFromCopy(const void *data, size_t size)
Create a Buffer from existing data, a deep copy of data will be made.
ulCreateBuffer
ULBuffer ulCreateBuffer(void *data, size_t size, void *user_data, ulDestroyBufferCallback destruction_callback)
Create a Buffer from existing, user-owned data without any copies.
CAPI_Defines.h
Various defines and utility functions for the C API.
ULExport
#define ULExport
Definition
CAPI_Defines.h:42
ULBuffer
struct C_Buffer * ULBuffer
Opaque handle to a Buffer object.
Definition
CAPI_Defines.h:99
Ultralight
CAPI
CAPI_Buffer.h
Docs
C++ API
C API
Version
2.0
2.0
latest
1.4