1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
|
/* $Id: s3.h $ */
/** @file
* IPRT - Simple Storage Service (S3) Communication API.
*/
/*
* Copyright (C) 2009-2022 Oracle and/or its affiliates.
*
* This file is part of VirtualBox base platform packages, as
* available from https://www.virtualbox.org.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation, in version 3 of the
* License.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <https://www.gnu.org/licenses>.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
* in the VirtualBox distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*
* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
*/
#ifndef IPRT_INCLUDED_s3_h
#define IPRT_INCLUDED_s3_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif
#include <iprt/types.h>
RT_C_DECLS_BEGIN
/** @defgroup grp_rt_s3 RTS3 - Simple Storage Service (S3) Communication API
* @ingroup grp_rt
* @{
*/
/** @todo the following three definitions may move the iprt/types.h later. */
/** RTS3 interface handle. */
typedef R3PTRTYPE(struct RTS3INTERNAL *) RTS3;
/** Pointer to a RTS3 interface handle. */
typedef RTS3 *PRTS3;
/** Nil RTS3 interface handle. */
#define NIL_RTS3 ((RTS3)0)
/**
* S3 progress callback.
*
* @returns Reserved, must be 0.
*
* @param uPercent The process completion percentage.
* @param pvUser The user parameter given to RTS3SetProgressCallback.
*/
typedef DECLCALLBACKTYPE(int, FNRTS3PROGRESS,(unsigned uPercent, void *pvUser));
/** Pointer to a S3 progress callback. */
typedef FNRTS3PROGRESS *PFNRTS3PROGRESS;
/** Pointer to an S3 bucket entry. */
typedef struct RTS3BUCKETENTRY *PRTS3BUCKETENTRY;
/** Pointer to a const S3 bucket entry. */
typedef struct RTS3BUCKETENTRY const *PCRTS3BUCKETENTRY;
/**
* RTS3 bucket entry.
*
* Represent a bucket of the S3 storage server. Bucket entries are chained as a
* doubly linked list using the pPrev & pNext member.
*
* @todo Consider making the entire list const unless there are plans for
* more APIs using this structure which requires the caller to create
* or modify it.
*/
typedef struct RTS3BUCKETENTRY
{
/** The previous element. */
PRTS3BUCKETENTRY pPrev;
/** The next element. */
PRTS3BUCKETENTRY pNext;
/** The name of the bucket. */
char const *pszName;
/** The creation date of the bucket as string. */
char const *pszCreationDate;
} RTS3BUCKETENTRY;
/** Pointer to an S3 key entry. */
typedef struct RTS3KEYENTRY *PRTS3KEYENTRY;
/** Pointer to a const S3 key entry. */
typedef struct RTS3KEYENTRY const *PCRTS3KEYENTRY;
/**
* RTS3 key entry.
*
* Represent a key of the S3 storage server. Key entries are chained as a doubly
* linked list using the pPrev & pNext member.
*
* @todo Consider making the entire list const unless there are plans for
* more APIs using this structure which requires the caller to create
* or modify it.
*/
typedef struct RTS3KEYENTRY
{
/** The previous element. */
PRTS3KEYENTRY pPrev;
/** The next element. */
PRTS3KEYENTRY pNext;
/** The name of the key. */
char const *pszName;
/** The date this key was last modified as string. */
char const *pszLastModified;
/** The size of the file behind this key in bytes. */
uint64_t cbFile;
} RTS3KEYENTRY;
/**
* Creates a RTS3 interface handle.
*
* @returns iprt status code.
*
* @param phS3 Where to store the RTS3 handle.
* @param pszAccessKey The access key for the S3 storage server.
* @param pszSecretKey The secret access key for the S3 storage server.
* @param pszBaseUrl The base URL of the S3 storage server.
* @param pszUserAgent An optional user agent string used in the HTTP
* communication.
*/
RTR3DECL(int) RTS3Create(PRTS3 phS3, const char *pszAccessKey, const char *pszSecretKey, const char *pszBaseUrl, const char *pszUserAgent);
/**
* Destroys a RTS3 interface handle.
*
* @returns iprt status code.
*
* @param hS3 Handle to the RTS3 interface.
*/
RTR3DECL(void) RTS3Destroy(RTS3 hS3);
/**
* Sets an optional progress callback.
*
* This callback function will be called when the completion percentage of an S3
* operation changes.
*
* @returns iprt status code.
*
* @param hS3 Handle to the RTS3 interface.
* @param pfnProgressCB The pointer to the progress function.
* @param pvUser The pvUser arg of FNRTS3PROGRESS.
*/
RTR3DECL(void) RTS3SetProgressCallback(RTS3 hS3, PFNRTS3PROGRESS pfnProgressCB, void *pvUser);
/**
* Gets a list of all available buckets on the S3 storage server.
*
* You have to delete ppBuckets after usage with RTS3BucketsDestroy.
*
* @returns iprt status code.
*
* @param hS3 Handle to the RTS3 interface.
* @param ppBuckets Where to store the pointer to the head of the
* returned bucket list. Consider the entire list
* read-only.
*/
RTR3DECL(int) RTS3GetBuckets(RTS3 hS3, PCRTS3BUCKETENTRY *ppBuckets);
/**
* Destroys the bucket list returned by RTS3GetBuckets.
*
* @returns iprt status code.
*
* @param pBuckets Pointer to the first bucket entry.
*/
RTR3DECL(int) RTS3BucketsDestroy(PCRTS3BUCKETENTRY pBuckets);
/**
* Creates a new bucket on the S3 storage server.
*
* This name have to be unique over all accounts on the S3 storage server.
*
* @returns iprt status code.
*
* @param hS3 Handle to the RTS3 interface.
* @param pszBucketName Name of the new bucket.
*/
RTR3DECL(int) RTS3CreateBucket(RTS3 hS3, const char *pszBucketName);
/**
* Deletes a bucket on the S3 storage server.
*
* The bucket must be empty.
*
* @returns iprt status code.
*
* @param hS3 Handle to the RTS3 interface.
* @param pszBucketName Name of the bucket to delete.
*/
RTR3DECL(int) RTS3DeleteBucket(RTS3 hS3, const char *pszBucketName);
/**
* Gets a list of all available keys in a bucket on the S3 storage server.
*
* You have to delete ppKeys after usage with RTS3KeysDestroy.
*
* @returns iprt status code.
*
* @param hS3 Handle to the RTS3 interface.
* @param pszBucketName Name of the bucket to delete.
* @param ppKeys Where to store the pointer to the head of the
* returned key list. Consider the entire list
* read-only.
*/
RTR3DECL(int) RTS3GetBucketKeys(RTS3 hS3, const char *pszBucketName, PCRTS3KEYENTRY *ppKeys);
/**
* Delete the key list returned by RTS3GetBucketKeys.
*
* @returns iprt status code.
*
* @param pKeys Pointer to the first key entry.
*/
RTR3DECL(int) RTS3KeysDestroy(PCRTS3KEYENTRY pKeys);
/**
* Deletes a key in a bucket on the S3 storage server.
*
* @returns iprt status code.
*
* @param hS3 Handle to the RTS3 interface.
* @param pszBucketName Name of the bucket contains pszKeyName.
* @param pszKeyName Name of the key to delete.
*/
RTR3DECL(int) RTS3DeleteKey(RTS3 hS3, const char *pszBucketName, const char *pszKeyName);
/**
* Downloads a key from a bucket into a file.
*
* The file must not exists.
*
* @returns iprt status code.
*
* @param hS3 Handle to the RTS3 interface.
* @param pszBucketName Name of the bucket that contains pszKeyName.
* @param pszKeyName Name of the key to download.
* @param pszFilename Name of the file to store the downloaded key as.
*/
RTR3DECL(int) RTS3GetKey(RTS3 hS3, const char *pszBucketName, const char *pszKeyName, const char *pszFilename);
/**
* Uploads the content of a file into a key in the specified bucked.
*
* @returns iprt status code.
*
* @param hS3 Handle to the RTS3 interface.
* @param pszBucketName Name of the bucket where the new key should be
* created.
* @param pszKeyName Name of the new key.
* @param pszFilename Name of the file to upload the content of.
*/
RTR3DECL(int) RTS3PutKey(RTS3 hS3, const char *pszBucketName, const char *pszKeyName, const char *pszFilename);
/** @} */
RT_C_DECLS_END
#endif /* !IPRT_INCLUDED_s3_h */
|
