Attention: this is a legacy library and thus not supported by Toradex anymore. We recommend that you use the new libraries for all Toradex modules. Please see the Toradex CE Libraries and Code Samples for up-to-date information.
As part of the AWS Free Usage Tier, you can get started with Amazon S3 for free. Upon sign-up a new AWS customer receives 5GB of Amazon S3 storage, 20,000 Get Requests, 2,000 Put Requests and 15GB of data transfer out each month for one year.
Notes:
For more information please refer this link: http://aws.amazon.com/s3/
Before calling any other function, call S3Open() with the input parameters S3Handle, AWS Access Id, AWS Secret Key and AWS S3 Region / Path.
The call will return TRUE if successful or FALSE if an error has occurred.
Use GetLastError() to get extended error details.
An example is described below (example for Singapore region S3 path is "s3-ap-southeast-1.amazonaws.com"):
// declare HS3 Handle to be used in all S3 based Function calls. HS3 S3Account1 = NULL; // temporary variable to store return of a function call BOOL result = 0; result = S3Open(S3Account1, “20CharacterAWSaccessID”, “40CharacterAWSSecretKey”, “s3Path”); if (result == TRUE) { printf(“S3Open Successful\n” } else { printf(“S3Open Error\n” }
The S3Account1 handle returned needs to be passed to all subsequent function calls.
The S3ListAllBuckets() function is used to get the list of all buckets in a region, which will be stored in a local file.
The function will return TRUE if successful or FALSE if the call fails. Use GetLastError() to get extended error details.
result = S3ListAllBuckets(s3Account1, 0, "\\Temp\\AllbucketList.txt", &s3ListALLBucketsRawDatabytes); if (result == TRUE) { printf(“S3ListAllBuckets Successful\n” } else { printf(“S3ListAllBuckets Error\n” }
The FindFirstBucket() function is used to get a particular bucket’s information from the list of all buckets in a region, which is stored in a local file by a call to function S3ListAllBuckets().
DWORD nextBucketPointer = 0 ; //Set to zero to get 1st bucket details. s3bucketData = (char *) malloc(1024); // Allocate memory to hold bucket details memset(s3bucketData, 0, 1024); // Clear the memory result = FindFirstBucket("\\Temp\\allbklist.txt", s3ListALLBucketsRawDatabytes, s3bucketData, 1024, &nextBucketPointer);
To get the next bucket details from the list stored in the local file, call the same function FindFirstBucket() with nextBucketPointer variable as 5th input parameter returned from previous call to FindFirstBucket().
memset(s3bucketData, 0 , 1024); // Clear the memory result = FindFirstBucket("\\Temp\\allbklist.txt", 3ListALLBucketsRawDatabytes, s3bucketData, 1024, &nextBucketPointer);
The S3ListBucket() function is used to get the list of all files in a bucket of a region, which will be stored in a local file.
This function works in a similar way as S3ListAllBuckets() works.
DWORD s3ListBucketRawDatabytes = 0; result = S3ListBucket(s3Account1, “/BucketName/”, "\\Temp\\bklist.txt", &s3ListBucketRawDatabytes); if (result == TRUE) { printf(“S3ListBucket Successful\n” } else { printf(“S3ListBucket Error\n” }
The FindFirstFileInBucket() function is used to get a file detail from the list of all files in a bucket of a region, stored in a local file by previous call to S3ListBucket().
DWORD nextFilePointer = 0 ; //Set to zero to get 1st file details. s3FileInBucketData = (char *)malloc(1024); // Allocate memory to hold file details memset(s3FileInBucketData, 0 , 1024); // Clear the memory result = FindFirstFileInBucket("\\Temp\\bklist.txt", s3ListBucketRawDatabytes, s3FileInBucketData, 1024, &nextFilePointer);
To get the next file details from the list stored in the local file, call the same function: FindFirstFileInBucket() with nextFilePointer variable as 5th input parameter returned from previous call to FindFirstFileInBucket()
memset(s3FileInBucketData, 0 , 1024); // Clear the memory result = FindFirstFileInBucket("\\Temp\\bklist.txt", s3ListBucketRawDatabytes, s3FileInBucketData, 1024, &nextFilePointer);
The S3MakeDirectory() function is used to create a new directory in an existing bucket.
result = S3MakeDirectory(s3Account1, “/BucketName/DirectoryName/”); if (result == FALSE) { printf("S3MakeDirectory Fails: Error Code:"); printf("%d\n", GetLastError()); } else { printf("S3MakeDirectory Success\n"); }
The S3RemoveDirectory() function is used to delete a directory in an existing bucket.
result = S3RemoveDirectory(s3Account1, “/BucketName/DirectoryName/”); if (result == FALSE) { printf("S3RemoveDirectory Fails: Error Code:"); printf("%d\n", GetLastError()); } else { printf("S3RemoveDirectory Success\n"); }
The S3DeleteFile() function is used to delete a file in an existing bucket.
result = S3DeleteFile (s3Account1, “/BucketName/FileName.txt”); if (result == FALSE) { printf("S3DeleteFile Fails: Error Code:"); printf("%d\n", GetLastError()); } else { printf("S3DeleteFile Success\n"); }
The S3DownloadFile() function is used to download a file from the S3 Bucket.
// User need to check if Destination File Already Exists or not to be safe if (S3DownloadFile(s3Account1, “/BucketName/File1.txt”, “\file.txt”, 10234, &bytesDownloaded, &ProgressCallback)) { printf("S3DownloadFile Successful\n"); } else { printf("S3DownloadFile Fails: Error Code: "); printf("%d\n", GetLastError()); } // Call back function definition void ProgressCallback(DWORD bytesDone, DWORD totalBytes) { printf("> %d bytes, %d \n", bytesDone, totalBytes); }
The S3UploadFile() function is used to upload a local file to the S3 bucket.
if (!S3UploadFile(s3Account1, “\LocalFile.txt”, uploadfilesize, “/BucketName/S3File.txt”, &bytesUploaded, &ProgressCallback)) { printf("UploadFile Fail\n"); } else { printf("UploadFile Success\n"); } // Call back function definition void ProgressCallback(DWORD bytesDone, DWORD totalBytes) { printf("> %d bytes, %d \n", bytesDone, totalBytes); }
The S3Close() function closes S3Handle opened by the call to S3Open() and frees all the resource allocated.
S3Close(&s3Account1);
