hb-blob: HarfBuzz Manual

## hb-blob hb-blob — Binary data containers |

## Functions

hb_blob_t * | hb_blob_create ()
hb_blob_t * | hb_blob_create_or_fail ()
hb_blob_t * | hb_blob_create_from_file ()
hb_blob_t * | hb_blob_create_from_file_or_fail ()
hb_blob_t * | hb_blob_create_sub_blob ()
hb_blob_t * | hb_blob_copy_writable_or_fail ()
hb_blob_t * | hb_blob_get_empty ()
hb_blob_t * | hb_blob_reference ()
void | hb_blob_destroy ()
hb_bool_t | hb_blob_set_user_data ()
void * | hb_blob_get_user_data ()
void | hb_blob_make_immutable ()
hb_bool_t | hb_blob_is_immutable ()
const char * | hb_blob_get_data ()
char * | hb_blob_get_data_writable ()
unsigned int | hb_blob_get_length ()

## Types and Values

typedef | hb_blob_t
enum | hb_memory_mode_t

## 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.

The filename is passed directly to the system on all platforms, except on Windows, where the filename is interpreted as UTF-8. Only if the filename is not valid UTF-8, it will be interpreted according to the system codepage.

#### 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 file.

The filename is passed directly to the system on all platforms, except on Windows, where the filename is interpreted as UTF-8. Only if the filename is not valid UTF-8, it will be interpreted according to the system codepage.

#### Parameters

file_name | A 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_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_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_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_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

### hb_blob_get_user_data ()

    void *
    hb_blob_get_user_data (const 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_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_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_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` .

[nullable][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_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

## 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_MODE_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 |