source: mainline/uspace/app/bithenge/blob.h@ 0d1a8fd

lfn serial ticket/834-toolchain-update topic/msim-upgrade topic/simplify-dev-export
Last change on this file since 0d1a8fd was d5070ef, checked in by Sean Bartell <wingedtachikoma@…>, 13 years ago

Bithenge: transforms and uint32le_transform

  • Property mode set to 100644
File size: 6.6 KB
Line 
1/*
2 * Copyright (c) 2012 Sean Bartell
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * - Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * - Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 * - The name of the author may not be used to endorse or promote products
15 * derived from this software without specific prior written permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28
29/** @addtogroup bithenge
30 * @{
31 */
32/**
33 * @file
34 * Raw binary blobs.
35 */
36
37#ifndef BITHENGE_BLOB_H_
38#define BITHENGE_BLOB_H_
39
40#include <sys/types.h>
41#include "tree.h"
42
43/** A blob of raw binary data.
44 * @implements bithenge_node_t */
45typedef struct {
46 /** @privatesection */
47 struct bithenge_node_t base;
48} bithenge_blob_t;
49
50/** Operations providing random access to binary data.
51 * @todo Should these be thread-safe? */
52typedef struct bithenge_random_access_blob_ops_t {
53 /** @copydoc bithenge_blob_t::bithenge_blob_size */
54 int (*size)(bithenge_blob_t *blob, aoff64_t *size);
55 /** @copydoc bithenge_blob_t::bithenge_blob_read */
56 int (*read)(bithenge_blob_t *blob, aoff64_t offset, char *buffer,
57 aoff64_t *size);
58 /** Destroy the blob.
59 * @param blob The blob.
60 * @return EOK on success or an error code from errno.h. */
61 int (*destroy)(bithenge_blob_t *blob);
62} bithenge_random_access_blob_ops_t;
63
64/** A blob built from an object that supports only sequential reading.
65 * @implements bithenge_blob_t */
66typedef struct {
67 /** @privatesection */
68 /** The base random-access blob. */
69 bithenge_blob_t base;
70 /** Operations providing sequential access. */
71 const struct bithenge_sequential_blob_ops_t *ops;
72 /** Buffer containing all data read. */
73 char *buffer;
74 /** Size of buffer. */
75 aoff64_t buffer_size;
76 /** Amount of data actually in buffer. */
77 aoff64_t data_size;
78} bithenge_sequential_blob_t;
79
80/** Operations providing sequential access to binary data.
81 * @memberof bithenge_sequential_blob_t */
82typedef struct bithenge_sequential_blob_ops_t {
83
84 /** Get the total size of the blob. If the total size cannot be
85 * determined easily, this field may be null or return an error,
86 * forcing the entire blob to be read to determine its size.
87 *
88 * @memberof bithenge_blob_t
89 * @param blob The blob.
90 * @param[out] size Total size of the blob.
91 * @return EOK on success or an error code from errno.h.
92 */
93 int (*size)(bithenge_sequential_blob_t *blob, aoff64_t *size);
94
95 /** Read the next part of the blob. If the requested data extends
96 * beyond the end of the blob, the data up until the end of the blob
97 * will be read.
98 *
99 * @param blob The blob.
100 * @param[out] buffer Buffer to read into. If an error occurs, the contents are
101 * undefined.
102 * @param[in,out] size Number of bytes to read; may be 0. If not enough
103 * data is left in the blob, the actual number of bytes read should be
104 * stored here. If an error occurs, the contents are undefined.
105 * @return EOK on success or an error code from errno.h.
106 */
107 int (*read)(bithenge_sequential_blob_t *blob, char *buffer,
108 aoff64_t *size);
109
110 /** Destroy the blob.
111 * @param blob The blob.
112 * @return EOK on success or an error code from errno.h. */
113 int (*destroy)(bithenge_sequential_blob_t *blob);
114} bithenge_sequential_blob_ops_t;
115
116/** Get the total size of the blob.
117 *
118 * @memberof bithenge_blob_t
119 * @param blob The blob.
120 * @param[out] size Total size of the blob.
121 * @return EOK on success or an error code from errno.h.
122 */
123static inline int bithenge_blob_size(bithenge_blob_t *blob, aoff64_t *size)
124{
125 assert(blob);
126 assert(blob->base.blob_ops);
127 return blob->base.blob_ops->size(blob, size);
128}
129
130/** Read part of the blob. If the requested data extends beyond the end of the
131 * blob, the data up until the end of the blob will be read. If the offset is
132 * beyond the end of the blob, even if the size is zero, an error will be
133 * returned.
134 *
135 * @memberof bithenge_blob_t
136 * @param blob The blob.
137 * @param offset Byte offset within the blob.
138 * @param[out] buffer Buffer to read into. If an error occurs, the contents are
139 * undefined.
140 * @param[in,out] size Number of bytes to read; may be 0. If the requested
141 * range extends beyond the end of the blob, the actual number of bytes read
142 * should be stored here. If an error occurs, the contents are undefined.
143 * @return EOK on success or an error code from errno.h.
144 */
145static inline int bithenge_blob_read(bithenge_blob_t *blob, aoff64_t offset,
146 char *buffer, aoff64_t *size)
147{
148 assert(blob);
149 assert(blob->base.blob_ops);
150 return blob->base.blob_ops->read(blob, offset, buffer, size);
151}
152
153/** Cast a blob node to a generic node.
154 * @memberof bithenge_blob_t
155 * @param blob The blob to cast.
156 * @return The blob node as a generic node. */
157static inline bithenge_node_t *bithenge_blob_as_node(bithenge_blob_t *blob)
158{
159 return &blob->base;
160}
161
162/** Cast a generic node to a blob node.
163 * @memberof bithenge_blob_t
164 * @param node The node to cast, which must be a blob node.
165 * @return The generic node as a blob node. */
166static inline bithenge_blob_t *bithenge_node_as_blob(bithenge_node_t *node)
167{
168 assert(node->type == BITHENGE_NODE_BLOB);
169 return (bithenge_blob_t *)node;
170}
171
172int bithenge_new_random_access_blob(bithenge_blob_t *blob,
173 const bithenge_random_access_blob_ops_t *ops);
174
175int bithenge_new_sequential_blob(bithenge_sequential_blob_t *blob,
176 const bithenge_sequential_blob_ops_t *ops);
177
178int bithenge_new_blob_from_data(bithenge_node_t **out, const void *data,
179 size_t len);
180
181int bithenge_new_blob_from_buffer(bithenge_node_t **out, const void *buffer,
182 size_t len, bool needs_free);
183
184bool bithenge_blob_equal(bithenge_blob_t *a, bithenge_blob_t *b);
185
186#endif
187
188/** @}
189 */
Note: See TracBrowser for help on using the repository browser.