spelling: fix misspellings
[gpgme.git] / src / data.h
1 /* data.h - Internal data object abstraction interface.
2    Copyright (C) 2002, 2004, 2005 g10 Code GmbH
3
4    This file is part of GPGME.
5
6    GPGME is free software; you can redistribute it and/or modify it
7    under the terms of the GNU Lesser General Public License as
8    published by the Free Software Foundation; either version 2.1 of
9    the License, or (at your option) any later version.
10
11    GPGME is distributed in the hope that it will be useful, but
12    WITHOUT ANY WARRANTY; without even the implied warranty of
13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14    Lesser General Public License for more details.
15
16    You should have received a copy of the GNU Lesser General Public
17    License along with this program; if not, write to the Free Software
18    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
19    02111-1307, USA.  */
20
21 #ifndef DATA_H
22 #define DATA_H
23
24 #if HAVE_CONFIG_H
25 #include <config.h>
26 #endif
27
28 #ifdef HAVE_SYS_TYPES_H
29 # include <sys/types.h>
30 #endif
31 #include <limits.h>
32 #include <stdint.h>
33
34 #include "gpgme.h"
35
36 \f
37 /* Read up to SIZE bytes into buffer BUFFER from the data object with
38    the handle DH.  Return the number of characters read, 0 on EOF and
39    -1 on error.  If an error occurs, errno is set.  */
40 typedef gpgme_ssize_t (*gpgme_data_read_cb) (gpgme_data_t dh,
41                                              void *buffer,
42                                              size_t size);
43
44 /* Write up to SIZE bytes from buffer BUFFER to the data object with
45    the handle DH.  Return the number of characters written, or -1 on
46    error.  If an error occurs, errno is set.  */
47 typedef gpgme_ssize_t (*gpgme_data_write_cb) (gpgme_data_t dh,
48                                               const void *buffer,
49                                               size_t size);
50
51 /* Set the current position from where the next read or write starts
52    in the data object with the handle DH to OFFSET, relative to
53    WHENCE.  */
54 typedef gpgme_off_t (*gpgme_data_seek_cb) (gpgme_data_t dh,
55                                             gpgme_off_t offset,
56                                             int whence);
57
58 /* Release the data object with the handle DH.  */
59 typedef void (*gpgme_data_release_cb) (gpgme_data_t dh);
60
61 /* Get the FD associated with the handle DH, or -1.  */
62 typedef int (*gpgme_data_get_fd_cb) (gpgme_data_t dh);
63
64 struct _gpgme_data_cbs
65 {
66   gpgme_data_read_cb read;
67   gpgme_data_write_cb write;
68   gpgme_data_seek_cb seek;
69   gpgme_data_release_cb release;
70   gpgme_data_get_fd_cb get_fd;
71 };
72
73 struct gpgme_data
74 {
75   struct _gpgme_data_cbs *cbs;
76   gpgme_data_encoding_t encoding;
77   unsigned int propidx;  /* Index into the property table.  */
78
79 #ifdef PIPE_BUF
80 #define BUFFER_SIZE PIPE_BUF
81 #else
82 #ifdef _POSIX_PIPE_BUF
83 #define BUFFER_SIZE _POSIX_PIPE_BUF
84 #else
85 #define BUFFER_SIZE 512
86 #endif
87 #endif
88   char pending[BUFFER_SIZE];
89   int pending_len;
90
91   /* File name of the data object.  */
92   char *file_name;
93
94   /* Hint on the to be expected total size of the data.  */
95   gpgme_off_t size_hint;
96
97   union
98   {
99     /* For gpgme_data_new_from_fd.  */
100     int fd;
101
102     /* For gpgme_data_new_from_stream.  */
103     FILE *stream;
104
105     /* For gpgme_data_new_from_estream.  */
106     gpgrt_stream_t e_stream;
107
108     /* For gpgme_data_new_from_cbs.  */
109     struct
110     {
111       gpgme_data_cbs_t cbs;
112       void *handle;
113     } user;
114
115     /* For gpgme_data_new_from_mem.  */
116     struct
117     {
118       char *buffer;
119       const char *orig_buffer;
120       /* Allocated size of BUFFER.  */
121       size_t size;
122       size_t length;
123       gpgme_off_t offset;
124     } mem;
125
126     /* For gpgme_data_new_from_read_cb.  */
127     struct
128     {
129       int (*cb) (void *, char *, size_t, size_t *);
130       void *handle;
131     } old_user;
132   } data;
133 };
134
135
136 /* The data property types.  */
137 typedef enum
138   {
139     DATA_PROP_NONE = 0,   /* Dummy property. */
140     DATA_PROP_BLANKOUT    /* Do not return the held data.  */
141   } data_prop_t;
142
143
144 \f
145 /* Return the data object's serial number for handle DH.  */
146 uint64_t _gpgme_data_get_dserial (gpgme_data_t dh);
147
148 /* Set an internal property of a data object.  */
149 gpg_error_t _gpgme_data_set_prop (gpgme_data_t dh, uint64_t dserial,
150                                   data_prop_t name, int value);
151
152 /* Get an internal property of a data object.  */
153 gpg_error_t _gpgme_data_get_prop (gpgme_data_t dh, uint64_t dserial,
154                                   data_prop_t name, int *r_value);
155
156 /* Create a new data object.  */
157 gpgme_error_t _gpgme_data_new (gpgme_data_t *r_dh,
158                                struct _gpgme_data_cbs *cbs);
159
160 void _gpgme_data_release (gpgme_data_t dh);
161
162 /* Get the file descriptor associated with DH, if possible.  Otherwise
163    return -1.  */
164 int _gpgme_data_get_fd (gpgme_data_t dh);
165
166 /* Get the size-hint value for DH or 0 if not available.  */
167 gpgme_off_t _gpgme_data_get_size_hint (gpgme_data_t dh);
168
169
170 #endif  /* DATA_H */