include/harfbuzz/hb-blob.h

0001 /*
0002  * Copyright © 2009  Red Hat, Inc.
0003  *
0004  *  This is part of HarfBuzz, a text shaping library.
0005  *
0006  * Permission is hereby granted, without written agreement and without
0007  * license or royalty fees, to use, copy, modify, and distribute this
0008  * software and its documentation for any purpose, provided that the
0009  * above copyright notice and the following two paragraphs appear in
0010  * all copies of this software.
0011  *
0012  * IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE TO ANY PARTY FOR
0013  * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
0014  * ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN
0015  * IF THE COPYRIGHT HOLDER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
0016  * DAMAGE.
0017  *
0018  * THE COPYRIGHT HOLDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
0019  * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
0020  * FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
0021  * ON AN "AS IS" BASIS, AND THE COPYRIGHT HOLDER HAS NO OBLIGATION TO
0022  * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
0023  *
0024  * Red Hat Author(s): Behdad Esfahbod
0025  */
0026
0027 #if !defined(HB_H_IN) && !defined(HB_NO_SINGLE_HEADER_ERROR)
0028 #error "Include <hb.h> instead."
0029 #endif
0030
0031 #ifndef HB_BLOB_H
0032 #define HB_BLOB_H
0033
0034 #include "hb-common.h"
0035
0036 HB_BEGIN_DECLS
0037
0038
0039 /**
0040  * hb_memory_mode_t:
0041  * @HB_MEMORY_MODE_DUPLICATE: HarfBuzz immediately makes a copy of the data.
0042  * @HB_MEMORY_MODE_READONLY: HarfBuzz client will never modify the data,
0043  *     and HarfBuzz will never modify the data.
0044  * @HB_MEMORY_MODE_WRITABLE: HarfBuzz client made a copy of the data solely
0045  *     for HarfBuzz, so HarfBuzz may modify the data.
0046  * @HB_MEMORY_MODE_READONLY_MAY_MAKE_WRITABLE: See above
0047  *
0048  * Data type holding the memory modes available to
0049  * client programs.
0050  *
0051  * Regarding these various memory-modes:
0052  *
0053  * - In no case shall the HarfBuzz client modify memory
0054  *   that is passed to HarfBuzz in a blob.  If there is
0055  *   any such possibility, @HB_MEMORY_MODE_DUPLICATE should be used
0056  *   such that HarfBuzz makes a copy immediately,
0057  *
0058  * - Use @HB_MEMORY_MODE_READONLY otherwise, unless you really really
0059  *   really know what you are doing,
0060  *
0061  * - @HB_MEMORY_MODE_WRITABLE is appropriate if you really made a
0062  *   copy of data solely for the purpose of passing to
0063  *   HarfBuzz and doing that just once (no reuse!),
0064  *
0065  * - If the font is mmap()ed, it's okay to use
0066  *   @HB_MEMORY_MODE_READONLY_MAY_MAKE_WRITABLE, however, using that mode
0067  *   correctly is very tricky.  Use @HB_MEMORY_MODE_READONLY instead.
0068  **/
0069 typedef enum {
0070   HB_MEMORY_MODE_DUPLICATE,
0071   HB_MEMORY_MODE_READONLY,
0072   HB_MEMORY_MODE_WRITABLE,
0073   HB_MEMORY_MODE_READONLY_MAY_MAKE_WRITABLE
0074 } hb_memory_mode_t;
0075
0076 /**
0077  * hb_blob_t:
0078  *
0079  * Data type for blobs. A blob wraps a chunk of binary
0080  * data and facilitates its lifecycle management between
0081  * a client program and HarfBuzz.
0082  *
0083  **/
0084 typedef struct hb_blob_t hb_blob_t;
0085
0086 HB_EXTERN hb_blob_t *
0087 hb_blob_create (const char        *data,
0088         unsigned int       length,
0089         hb_memory_mode_t   mode,
0090         void              *user_data,
0091         hb_destroy_func_t  destroy);
0092
0093 HB_EXTERN hb_blob_t *
0094 hb_blob_create_or_fail (const char        *data,
0095             unsigned int       length,
0096             hb_memory_mode_t   mode,
0097             void              *user_data,
0098             hb_destroy_func_t  destroy);
0099
0100 HB_EXTERN hb_blob_t *
0101 hb_blob_create_from_file (const char *file_name);
0102
0103 HB_EXTERN hb_blob_t *
0104 hb_blob_create_from_file_or_fail (const char *file_name);
0105
0106 /* Always creates with MEMORY_MODE_READONLY.
0107  * Even if the parent blob is writable, we don't
0108  * want the user of the sub-blob to be able to
0109  * modify the parent data as that data may be
0110  * shared among multiple sub-blobs.
0111  */
0112 HB_EXTERN hb_blob_t *
0113 hb_blob_create_sub_blob (hb_blob_t    *parent,
0114              unsigned int  offset,
0115              unsigned int  length);
0116
0117 HB_EXTERN hb_blob_t *
0118 hb_blob_copy_writable_or_fail (hb_blob_t *blob);
0119
0120 HB_EXTERN hb_blob_t *
0121 hb_blob_get_empty (void);
0122
0123 HB_EXTERN hb_blob_t *
0124 hb_blob_reference (hb_blob_t *blob);
0125
0126 HB_EXTERN void
0127 hb_blob_destroy (hb_blob_t *blob);
0128
0129 HB_EXTERN hb_bool_t
0130 hb_blob_set_user_data (hb_blob_t          *blob,
0131                hb_user_data_key_t *key,
0132                void *              data,
0133                hb_destroy_func_t   destroy,
0134                hb_bool_t           replace);
0135
0136
0137 HB_EXTERN void *
0138 hb_blob_get_user_data (const hb_blob_t    *blob,
0139                hb_user_data_key_t *key);
0140
0141
0142 HB_EXTERN void
0143 hb_blob_make_immutable (hb_blob_t *blob);
0144
0145 HB_EXTERN hb_bool_t
0146 hb_blob_is_immutable (hb_blob_t *blob);
0147
0148
0149 HB_EXTERN unsigned int
0150 hb_blob_get_length (hb_blob_t *blob);
0151
0152 HB_EXTERN const char *
0153 hb_blob_get_data (hb_blob_t *blob, unsigned int *length);
0154
0155 HB_EXTERN char *
0156 hb_blob_get_data_writable (hb_blob_t *blob, unsigned int *length);
0157
0158 HB_END_DECLS
0159
0160 #endif /* HB_BLOB_H */