## hb-blob

hb-blob — Binary data containers

## Functions

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

## Types and Values

typedef | hb_blob_t
enum | hb_memory_mode_t

## Object Hierarchy

        GBoxed
        ╰── hb_blob_t
        GEnum
        ╰── 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. |

#### 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_from_file ()

    hb_blob_t *
    hb_blob_create_from_file (const char *file_name);

#### Parameters

file_name | font filename. |

#### Returns

A hb_blob_t pointer with the content of the file

Since: 1.7.7

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

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);

#### Parameters

blob | a blob. |
length | . | [out]

#### Returns

.

[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);

#### 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);

[skip]

#### Parameters

blob | a blob. |
key | key for data to get. |

#### Returns

.

[transfer none]

Since: 0.9.2

### hb_blob_is_immutable ()

    hb_bool_t
    hb_blob_is_immutable (hb_blob_t *blob);

#### Parameters

blob | a blob. |

#### Returns

TODO

Since: 0.9.2

### hb_blob_make_immutable ()

    void
    hb_blob_make_immutable (hb_blob_t *blob);

#### 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);

[skip]

#### Parameters

blob | a blob. |
key | key for data to set. |
data | data to set. |
destroy | callback to call when `data` is not needed anymore. |
replace | whether to replace an existing data with the same key. |

Since: 0.9.2

## Types and Values

### hb_blob_t

    typedef struct hb_blob_t hb_blob_t;

### enum hb_memory_mode_t

#### Members

HB_MEMORY_MODE_DUPLICATE |  |
HB_MEMORY_MODE_READONLY |  |
HB_MEMORY_MODE_WRITABLE |  |
HB_MEMORY_MODE_READONLY_MAY_MAKE_WRITABLE |  |