VirtualBox

source: vbox/trunk/include/iprt/s3.h@ 28794

Last change on this file since 28794 was 25645, checked in by vboxsync, 15 years ago

IPRT,DoxyFile.Core: Mopped up the errors in the IPRT doxygen run.

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette