← Back to branch summary

~ubuntu-branches/ubuntu/quantal/ceph/quantal

« back to all changes in this revision

Viewing changes to doc/api/s3/cpp.rst

  • Committer: Package Import Robot
  • Author(s): James Page
  • Date: 2012-07-16 09:56:24 UTC
  • mfrom: (0.3.11)
  • mto: This revision was merged to the branch mainline in revision 17.
  • Revision ID: package-import@ubuntu.com-20120716095624-azr2w4hbhei1rxmx
Tags: upstream-0.48
Import upstream version 0.48

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/api/s3/cpp.rst
 
1
.. _cpp:
 
2
 
 
3
C++ S3 Examples
 
4
===============
 
5
 
 
6
Setup
 
7
-----
 
8
 
 
9
The following contains includes and globals that will be used in later examples:
 
10
 
 
11
.. code-block:: cpp
 
12
 
 
13
        #include "libs3.h"
 
14
        #include <stdlib.h>
 
15
        #include <iostream>
 
16
        #include <fstream>
 
17
 
 
18
        const char access_key[] = "ACCESS_KEY";
 
19
        const char secret_key[] = "SECRET_KEY";
 
20
        const char host[] = "HOST";
 
21
        const char sample_bucket[] = "sample_bucket";
 
22
        const char sample_key[] = "hello.txt";
 
23
        const char sample_file[] = "resource/hello.txt";
 
24
 
 
25
        S3BucketContext bucketContext =
 
26
        {
 
27
                host,
 
28
                sample_bucket,
 
29
                S3ProtocolHTTP,
 
30
                S3UriStylePath,
 
31
                access_key,
 
32
                secret_key
 
33
        };
 
34
 
 
35
        S3Status responsePropertiesCallback(
 
36
                        const S3ResponseProperties *properties,
 
37
                        void *callbackData)
 
38
        {
 
39
                return S3StatusOK;
 
40
        }
 
41
 
 
42
        static void responseCompleteCallback(
 
43
                        S3Status status,
 
44
                        const S3ErrorDetails *error,
 
45
                        void *callbackData)
 
46
        {
 
47
                return;
 
48
        }
 
49
 
 
50
        S3ResponseHandler responseHandler =
 
51
        {
 
52
                &responsePropertiesCallback,
 
53
                &responseCompleteCallback
 
54
        };
 
55
 
 
56
 
 
57
Creating (and Closing) a Connection
 
58
-----------------------------------
 
59
 
 
60
This creates a connection so that you can interact with the server.
 
61
 
 
62
.. code-block:: cpp
 
63
 
 
64
        S3_initialize("s3", S3_INIT_ALL, host);
 
65
        // Do stuff...
 
66
        S3_deinitialize();
 
67
 
 
68
 
 
69
Listing Owned Buckets
 
70
---------------------
 
71
 
 
72
This gets a list of Buckets that you own.
 
73
This also prints out the bucket name, owner ID, and display name
 
74
for each bucket.
 
75
 
 
76
.. code-block:: cpp
 
77
 
 
78
        static S3Status listServiceCallback(
 
79
                        const char *ownerId,
 
80
                        const char *ownerDisplayName,
 
81
                        const char *bucketName,
 
82
                        int64_t creationDate, void *callbackData)
 
83
        {
 
84
                bool *header_printed = (bool*) callbackData;
 
85
                if (!*header_printed) {
 
86
                        *header_printed = true;
 
87
                        printf("%-22s", "       Bucket");
 
88
                        printf("  %-20s  %-12s", "     Owner ID", "Display Name");
 
89
                        printf("\n");
 
90
                        printf("----------------------");
 
91
                        printf("  --------------------" "  ------------");
 
92
                        printf("\n");
 
93
                }
 
94
 
 
95
                printf("%-22s", bucketName);
 
96
                printf("  %-20s  %-12s", ownerId ? ownerId : "", ownerDisplayName ? ownerDisplayName : "");
 
97
                printf("\n");
 
98
 
 
99
                return S3StatusOK;
 
100
        }
 
101
 
 
102
        S3ListServiceHandler listServiceHandler =
 
103
        {
 
104
                responseHandler,
 
105
                &listServiceCallback
 
106
        };
 
107
        bool header_printed = false;
 
108
        S3_list_service(S3ProtocolHTTP, access_key, secret_key, host, 0, &listServiceHandler, &header_printed);
 
109
 
 
110
 
 
111
Creating a Bucket
 
112
-----------------
 
113
 
 
114
This creates a new bucket.
 
115
 
 
116
.. code-block:: cpp
 
117
 
 
118
        S3_create_bucket(S3ProtocolHTTP, access_key, secret_key, host, sample_bucket, S3CannedAclPrivate, NULL, NULL, &responseHandler, NULL);
 
119
 
 
120
 
 
121
Listing a Bucket's Content
 
122
--------------------------
 
123
 
 
124
This gets a list of objects in the bucket.
 
125
This also prints out each object's name, the file size, and
 
126
last modified date.
 
127
 
 
128
.. code-block:: cpp
 
129
 
 
130
        static S3Status listBucketCallback(
 
131
                        int isTruncated,
 
132
                        const char *nextMarker,
 
133
                        int contentsCount,
 
134
                        const S3ListBucketContent *contents,
 
135
                        int commonPrefixesCount,
 
136
                        const char **commonPrefixes,
 
137
                        void *callbackData)
 
138
        {
 
139
                printf("%-22s", "      Object Name");
 
140
                printf("  %-5s  %-20s", "Size", "   Last Modified");
 
141
                printf("\n");
 
142
                printf("----------------------");
 
143
                printf("  -----" "  --------------------");
 
144
                printf("\n");
 
145
 
 
146
            for (int i = 0; i < contentsCount; i++) {
 
147
                char timebuf[256];
 
148
                        char sizebuf[16];
 
149
                const S3ListBucketContent *content = &(contents[i]);
 
150
                        time_t t = (time_t) content->lastModified;
 
151
 
 
152
                        strftime(timebuf, sizeof(timebuf), "%Y-%m-%dT%H:%M:%SZ", gmtime(&t));
 
153
                        sprintf(sizebuf, "%5llu", (unsigned long long) content->size);
 
154
                        printf("%-22s  %s  %s\n", content->key, sizebuf, timebuf);
 
155
            }
 
156
 
 
157
            return S3StatusOK;
 
158
        }
 
159
 
 
160
        S3ListBucketHandler listBucketHandler =
 
161
        {
 
162
                responseHandler,
 
163
                &listBucketCallback
 
164
        };
 
165
        S3_list_bucket(&bucketContext, NULL, NULL, NULL, 0, NULL, &listBucketHandler, NULL);
 
166
 
 
167
The output will look something like this::
 
168
 
 
169
   myphoto1.jpg 251262  2011-08-08T21:35:48.000Z
 
170
   myphoto2.jpg 262518  2011-08-08T21:38:01.000Z
 
171
 
 
172
 
 
173
Deleting a Bucket
 
174
-----------------
 
175
 
 
176
.. note::
 
177
 
 
178
   The Bucket must be empty! Otherwise it won't work!
 
179
 
 
180
.. code-block:: cpp
 
181
 
 
182
        S3_delete_bucket(S3ProtocolHTTP, S3UriStylePath, access_key, secret_key, host, sample_bucket, NULL, &responseHandler, NULL);
 
183
 
 
184
 
 
185
Creating an Object (from a file)
 
186
--------------------------------
 
187
 
 
188
This creates a file ``hello.txt``.
 
189
 
 
190
.. code-block:: cpp
 
191
 
 
192
        #include <sys/stat.h>
 
193
        typedef struct put_object_callback_data
 
194
        {
 
195
            FILE *infile;
 
196
            uint64_t contentLength;
 
197
        } put_object_callback_data;
 
198
 
 
199
 
 
200
        static int putObjectDataCallback(int bufferSize, char *buffer, void *callbackData)
 
201
        {
 
202
            put_object_callback_data *data = (put_object_callback_data *) callbackData;
 
203
 
 
204
            int ret = 0;
 
205
 
 
206
            if (data->contentLength) {
 
207
                int toRead = ((data->contentLength > (unsigned) bufferSize) ? (unsigned) bufferSize : data->contentLength);
 
208
                        ret = fread(buffer, 1, toRead, data->infile);
 
209
            }
 
210
            data->contentLength -= ret;
 
211
            return ret;
 
212
        }
 
213
 
 
214
        put_object_callback_data data;
 
215
        struct stat statbuf;
 
216
        if (stat(sample_file, &statbuf) == -1) {
 
217
                fprintf(stderr, "\nERROR: Failed to stat file %s: ", sample_file);
 
218
                perror(0);
 
219
                exit(-1);
 
220
        }
 
221
 
 
222
        int contentLength = statbuf.st_size;
 
223
        data.contentLength = contentLength;
 
224
 
 
225
        if (!(data.infile = fopen(sample_file, "r"))) {
 
226
                fprintf(stderr, "\nERROR: Failed to open input file %s: ", sample_file);
 
227
                perror(0);
 
228
                exit(-1);
 
229
        }
 
230
 
 
231
        S3PutObjectHandler putObjectHandler =
 
232
        {
 
233
                responseHandler,
 
234
                &putObjectDataCallback
 
235
        };
 
236
 
 
237
        S3_put_object(&bucketContext, sample_key, contentLength, NULL, NULL, &putObjectHandler, &data);
 
238
 
 
239
 
 
240
Download an Object (to a file)
 
241
------------------------------
 
242
 
 
243
This downloads a file and prints the contents.
 
244
 
 
245
.. code-block:: cpp
 
246
 
 
247
        static S3Status getObjectDataCallback(int bufferSize, const char *buffer, void *callbackData)
 
248
        {
 
249
                FILE *outfile = (FILE *) callbackData;
 
250
                size_t wrote = fwrite(buffer, 1, bufferSize, outfile);
 
251
                return ((wrote < (size_t) bufferSize) ? S3StatusAbortedByCallback : S3StatusOK);
 
252
        }
 
253
 
 
254
        S3GetObjectHandler getObjectHandler =
 
255
        {
 
256
                responseHandler,
 
257
                &getObjectDataCallback
 
258
        };
 
259
        FILE *outfile = stdout;
 
260
        S3_get_object(&bucketContext, sample_key, NULL, 0, 0, NULL, &getObjectHandler, outfile);
 
261
 
 
262
 
 
263
Delete an Object
 
264
----------------
 
265
 
 
266
This deletes an object.
 
267
 
 
268
.. code-block:: cpp
 
269
 
 
270
        S3ResponseHandler deleteResponseHandler =
 
271
        {
 
272
                0,
 
273
                &responseCompleteCallback
 
274
        };
 
275
        S3_delete_object(&bucketContext, sample_key, 0, &deleteResponseHandler, 0);
 
276
 
 
277
 
 
278
Change an Object's ACL
 
279
----------------------
 
280
 
 
281
This changes an object's ACL to grant full control to another user.
 
282
 
 
283
 
 
284
.. code-block:: cpp
 
285
 
 
286
        #include <string.h>
 
287
        char ownerId[] = "owner";
 
288
        char ownerDisplayName[] = "owner";
 
289
        char granteeId[] = "grantee";
 
290
        char granteeDisplayName[] = "grantee";
 
291
 
 
292
        S3AclGrant grants[] = {
 
293
                {
 
294
                        S3GranteeTypeCanonicalUser,
 
295
                        {{}},
 
296
                        S3PermissionFullControl
 
297
                },
 
298
                {
 
299
                        S3GranteeTypeCanonicalUser,
 
300
                        {{}},
 
301
                        S3PermissionReadACP
 
302
                },
 
303
                {
 
304
                        S3GranteeTypeAllUsers,
 
305
                        {{}},
 
306
                        S3PermissionRead
 
307
                }
 
308
        };
 
309
 
 
310
        strncpy(grants[0].grantee.canonicalUser.id, ownerId, S3_MAX_GRANTEE_USER_ID_SIZE);
 
311
        strncpy(grants[0].grantee.canonicalUser.displayName, ownerDisplayName, S3_MAX_GRANTEE_DISPLAY_NAME_SIZE);
 
312
 
 
313
        strncpy(grants[1].grantee.canonicalUser.id, granteeId, S3_MAX_GRANTEE_USER_ID_SIZE);
 
314
        strncpy(grants[1].grantee.canonicalUser.displayName, granteeDisplayName, S3_MAX_GRANTEE_DISPLAY_NAME_SIZE);
 
315
 
 
316
        S3_set_acl(&bucketContext, sample_key, ownerId, ownerDisplayName, 3, grants, 0, &responseHandler, 0);
 
317
 
 
318
 
 
319
Generate Object Download URL (signed)
 
320
-------------------------------------
 
321
 
 
322
This generates a signed download URL that will be valid for 5 minutes.
 
323
 
 
324
.. code-block:: cpp
 
325
 
 
326
        #include <time.h>
 
327
        char buffer[S3_MAX_AUTHENTICATED_QUERY_STRING_SIZE];
 
328
        int64_t expires = time(NULL) + 60 * 5; // Current time + 5 minutes
 
329
 
 
330
        S3_generate_authenticated_query_string(buffer, &bucketContext, sample_key, expires, NULL);
 
331