hb-blob

hb-blob — Binary data containers

Functions

Types and Values

Includes

#include <hb.h>

Description

Blobs wrap a chunk of binary data to handle lifecycle management of data while it is passed between client and HarfBuzz. Blobs are primarily used to create font faces, but also to access font face tables, as well as pass around other binary data.

Functions

hb_blob_create ()

hb_blob_t *
hb_blob_create (const char *data,
                unsigned int length,
                hb_memory_mode_t mode,
                void *user_data,
                hb_destroy_func_t destroy);

Creates a new "blob" object wrapping data . The mode parameter is used to negotiate ownership and lifecycle of data .

[skip]

Parameters

data

Pointer to blob data.

 

length

Length of data in bytes.

 

mode

Memory mode for data .

 

user_data

Data parameter to pass to destroy .

 

destroy

Callback to call when data is not needed anymore.

[nullable]

Returns

New blob, or the empty blob if something failed or if length is zero. Destroy with hb_blob_destroy().

Since: 0.9.2


hb_blob_create_or_fail ()

hb_blob_t *
hb_blob_create_or_fail (const char *data,
                        unsigned int length,
                        hb_memory_mode_t mode,
                        void *user_data,
                        hb_destroy_func_t destroy);

Creates a new "blob" object wrapping data . The mode parameter is used to negotiate ownership and lifecycle of data .

Note that this function returns a freshly-allocated empty blob even if length is zero. This is in contrast to hb_blob_create(), which returns the singleton empty blob (as returned by hb_blob_get_empty()) if length is zero.

[skip]

Parameters

data

Pointer to blob data.

 

length

Length of data in bytes.

 

mode

Memory mode for data .

 

user_data

Data parameter to pass to destroy .

 

destroy

Callback to call when data is not needed anymore.

[nullable]

Returns

New blob, or NULL if failed. Destroy with hb_blob_destroy().

Since: 2.8.2


hb_blob_create_from_file ()

hb_blob_t *
hb_blob_create_from_file (const char *file_name);

Creates a new blob containing the data from the specified binary font file.

Parameters

file_name

A font filename

 

Returns

An hb_blob_t pointer with the content of the file, or hb_blob_get_empty() if failed.

Since: 1.7.7


hb_blob_create_from_file_or_fail ()

hb_blob_t *
hb_blob_create_from_file_or_fail (const char *file_name);

Creates a new blob containing the data from the specified binary font file.

Parameters

file_name

A font filename

 

Returns

An hb_blob_t pointer with the content of the file, or NULL if failed.

Since: 2.8.2


hb_blob_create_sub_blob ()

hb_blob_t *
hb_blob_create_sub_blob (hb_blob_t *parent,
                         unsigned int offset,
                         unsigned int length);

Returns a blob that represents a range of bytes in parent . The new blob is always created with HB_MEMORY_MODE_READONLY, meaning that it will never modify data in the parent blob. The parent data is not expected to be modified, and will result in undefined behavior if it is.

Makes parent immutable.

Parameters

parent

Parent blob.

 

offset

Start offset of sub-blob within parent , in bytes.

 

length

Length of sub-blob.

 

Returns

New blob, or the empty blob if something failed or if length is zero or offset is beyond the end of parent 's data. Destroy with hb_blob_destroy().

Since: 0.9.2


hb_blob_copy_writable_or_fail ()

hb_blob_t *
hb_blob_copy_writable_or_fail (hb_blob_t *blob);

Makes a writable copy of blob .

Parameters

blob

A blob.

 

Returns

The new blob, or nullptr if allocation failed

Since: 1.8.0


hb_blob_destroy ()

void
hb_blob_destroy (hb_blob_t *blob);

Decreases the reference count on blob , and if it reaches zero, destroys blob , freeing all memory, possibly calling the destroy-callback the blob was created for if it has not been called already.

See TODO:link object types for more information.

[skip]

Parameters

blob

a blob.

 

Since: 0.9.2


hb_blob_get_data ()

const char *
hb_blob_get_data (hb_blob_t *blob,
                  unsigned int *length);

Fetches the data from a blob.

Parameters

blob

a blob.

 

length

The length in bytes of the data retrieved.

[out]

Returns

the byte data of blob .

[transfer none][array length=length]

Since: 0.9.2


hb_blob_get_data_writable ()

char *
hb_blob_get_data_writable (hb_blob_t *blob,
                           unsigned int *length);

Tries to make blob data writable (possibly copying it) and return pointer to data.

Fails if blob has been made immutable, or if memory allocation fails.

Parameters

blob

a blob.

 

length

output length of the writable data.

[out]

Returns

Writable blob data, or NULL if failed.

[transfer none][array length=length]

Since: 0.9.2


hb_blob_get_empty ()

hb_blob_t *
hb_blob_get_empty (void);

Returns the singleton empty blob.

See TODO:link object types for more information.

Returns

The empty blob.

[transfer full]

Since: 0.9.2


hb_blob_get_length ()

unsigned int
hb_blob_get_length (hb_blob_t *blob);

Fetches the length of a blob's data.

Parameters

blob

a blob.

 

Returns

the length of blob data in bytes.

Since: 0.9.2


hb_blob_get_user_data ()

void *
hb_blob_get_user_data (hb_blob_t *blob,
                       hb_user_data_key_t *key);

Fetches the user data associated with the specified key, attached to the specified font-functions structure.

[skip]

Parameters

blob

a blob

 

key

The user-data key to query

 

Returns

A pointer to the user data.

[transfer none]

Since: 0.9.2


hb_blob_is_immutable ()

hb_bool_t
hb_blob_is_immutable (hb_blob_t *blob);

Tests whether a blob is immutable.

Parameters

blob

a blob.

 

Returns

true if blob is immutable, false otherwise

Since: 0.9.2


hb_blob_make_immutable ()

void
hb_blob_make_immutable (hb_blob_t *blob);

Makes a blob immutable.

Parameters

blob

a blob

 

Since: 0.9.2


hb_blob_reference ()

hb_blob_t *
hb_blob_reference (hb_blob_t *blob);

Increases the reference count on blob .

See TODO:link object types for more information.

[skip]

Parameters

blob

a blob.

 

Returns

blob .

Since: 0.9.2


hb_blob_set_user_data ()

hb_bool_t
hb_blob_set_user_data (hb_blob_t *blob,
                       hb_user_data_key_t *key,
                       void *data,
                       hb_destroy_func_t destroy,
                       hb_bool_t replace);

Attaches a user-data key/data pair to the specified blob.

[skip]

Parameters

blob

An hb_blob_t

 

key

The user-data key to set

 

data

A pointer to the user data to set

 

destroy

A callback to call when data is not needed anymore.

[nullable]

replace

Whether to replace an existing data with the same key

 

Returns

true if success, false otherwise

Since: 0.9.2

Types and Values

hb_blob_t

typedef struct hb_blob_t hb_blob_t;

Data type for blobs. A blob wraps a chunk of binary data and facilitates its lifecycle management between a client program and HarfBuzz.


enum hb_memory_mode_t

Data type holding the memory modes available to client programs.

Regarding these various memory-modes:

  • In no case shall the HarfBuzz client modify memory that is passed to HarfBuzz in a blob. If there is any such possibility, HB_MEMORY_MODE_DUPLICATE should be used such that HarfBuzz makes a copy immediately,

  • Use HB_MEMORY_MODE_READONLY otherwise, unless you really really really know what you are doing,

  • HB_MEMORY_MODE_WRITABLE is appropriate if you really made a copy of data solely for the purpose of passing to HarfBuzz and doing that just once (no reuse!),

  • If the font is mmap()ed, it's okay to use HB_MEMORY_READONLY_MAY_MAKE_WRITABLE , however, using that mode correctly is very tricky. Use HB_MEMORY_MODE_READONLY instead.

Members

HB_MEMORY_MODE_DUPLICATE

HarfBuzz immediately makes a copy of the data.

 

HB_MEMORY_MODE_READONLY

HarfBuzz client will never modify the data, and HarfBuzz will never modify the data.

 

HB_MEMORY_MODE_WRITABLE

HarfBuzz client made a copy of the data solely for HarfBuzz, so HarfBuzz may modify the data.

 

HB_MEMORY_MODE_READONLY_MAY_MAKE_WRITABLE

See above