src/ceph/doc/radosgw/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, NULL, &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, NULL, 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