/usr/include/libs3.h is in libs3-dev 2.0-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 | /** **************************************************************************
* libs3.h
*
* Copyright 2008 Bryan Ischo <bryan@ischo.com>
*
* This file is part of libs3.
*
* libs3 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, version 3 of the License.
*
* In addition, as a special exception, the copyright holders give
* permission to link the code of this library and its programs with the
* OpenSSL library, and distribute linked combinations including the two.
*
* libs3 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 version 3
* along with libs3, in a file named COPYING. If not, see
* <http://www.gnu.org/licenses/>.
*
************************************************************************** **/
#ifndef LIBS3_H
#define LIBS3_H
#include <stdint.h>
#include <sys/select.h>
#ifdef __cplusplus
extern "C" {
#endif
/** **************************************************************************
* Overview
* --------
*
* This library provides an API for using Amazon's S3 service (see
* http://s3.amazonaws.com). Its design goals are:
*
* - To provide a simple and straightforward API for accessing all of S3's
* functionality
* - To not require the developer using libs3 to need to know anything about:
* - HTTP
* - XML
* - SSL
* In other words, this API is meant to stand on its own, without requiring
* any implicit knowledge of how S3 services are accessed using HTTP
* protocols.
* - To be usable from multithreaded code
* - To be usable by code which wants to process multiple S3 requests
* simultaneously from a single thread
* - To be usable in the simple, straightforward way using sequentialized
* blocking requests
*
* The general usage pattern of libs3 is:
*
* - Initialize libs3 once per program by calling S3_initialize() at program
* start up time
* - Make any number of requests to S3 for getting, putting, or listing
* S3 buckets or objects, or modifying the ACLs associated with buckets
* or objects, using one of three general approaches:
* 1. Simple blocking requests, one at a time
* 2. Multiple threads each making simple blocking requests
* 3. From a single thread, managing multiple S3 requests simultaneously
* using file descriptors and a select()/poll() loop
* - Shut down libs3 at program exit time by calling S3_deinitialize()
*
* All functions which send requests to S3 return their results via a set of
* callback functions which must be supplied to libs3 at the time that the
* request is initiated. libs3 will call these functions back in the thread
* calling the libs3 function if blocking requests are made (i.e., if the
* S3RequestContext for the function invocation is passed in as NULL).
* If an S3RequestContext is used to drive multiple S3 requests
* simultaneously, then the callbacks will be made from the thread which
* calls S3_runall_request_context() or S3_runonce_request_context(), or
* possibly from the thread which calls S3_destroy_request_context(), if
* S3 requests are in progress at the time that this function is called.
*
* NOTE: Response headers from Amazon S3 are limited to 4K (2K of metas is all
* that Amazon supports, and libs3 allows Amazon an additional 2K of headers).
*
* NOTE: Because HTTP and the S3 REST protocol are highly under-specified,
* libs3 must make some assumptions about the maximum length of certain HTTP
* elements (such as headers) that it will accept. While efforts have been
* made to enforce maximums which are beyond that expected to be needed by any
* user of S3, it is always possible that these maximums may be too low in
* some rare circumstances. Bug reports should this unlikely situation occur
* would be most appreciated.
*
* Threading Rules
* ---------------
*
* 1. All arguments passed to any function must not be modified directly until
* the function returns.
* 2. All S3RequestContext and S3Request arguments passed to all functions may
* not be passed to any other libs3 function by any other thread until the
* function returns.
* 3. All functions may be called simultaneously by multiple threads as long
* as (1) and (2) are observed, EXCEPT for S3_initialize(), which must be
* called from one thread at a time only.
* 4. All callbacks will be made in the thread of the caller of the function
* which invoked them, so the caller of all libs3 functions should not hold
* locks that it would try to re-acquire in a callback, as this may
* deadlock.
************************************************************************** **/
/** **************************************************************************
* Constants
************************************************************************** **/
/**
* S3_MAX_HOSTNAME_SIZE is the maximum size we allow for a host name
**/
#define S3_MAX_HOSTNAME_SIZE 255
/**
* This is the default hostname that is being used for the S3 requests
**/
#define S3_DEFAULT_HOSTNAME "s3.amazonaws.com"
/**
* S3_MAX_BUCKET_NAME_SIZE is the maximum size of a bucket name.
**/
#define S3_MAX_BUCKET_NAME_SIZE 255
/**
* S3_MAX_KEY_SIZE is the maximum size of keys that Amazon S3 supports.
**/
#define S3_MAX_KEY_SIZE 1024
/**
* S3_MAX_METADATA_SIZE is the maximum number of bytes allowed for
* x-amz-meta header names and values in any request passed to Amazon S3
**/
#define S3_MAX_METADATA_SIZE 2048
/**
* S3_METADATA_HEADER_NAME_PREFIX is the prefix of an S3 "meta header"
**/
#define S3_METADATA_HEADER_NAME_PREFIX "x-amz-meta-"
/**
* S3_MAX_METADATA_COUNT is the maximum number of x-amz-meta- headers that
* could be included in a request to S3. The smallest meta header is
* "x-amz-meta-n: v". Since S3 doesn't count the ": " against the total, the
* smallest amount of data to count for a header would be the length of
* "x-amz-meta-nv".
**/
#define S3_MAX_METADATA_COUNT \
(S3_MAX_METADATA_SIZE / (sizeof(S3_METADATA_HEADER_NAME_PREFIX "nv") - 1))
/**
* S3_MAX_ACL_GRANT_COUNT is the maximum number of ACL grants that may be
* set on a bucket or object at one time. It is also the maximum number of
* ACL grants that the XML ACL parsing routine will parse.
**/
#define S3_MAX_ACL_GRANT_COUNT 100
/**
* This is the maximum number of characters (including terminating \0) that
* libs3 supports in an ACL grantee email address.
**/
#define S3_MAX_GRANTEE_EMAIL_ADDRESS_SIZE 128
/**
* This is the maximum number of characters (including terminating \0) that
* libs3 supports in an ACL grantee user id.
**/
#define S3_MAX_GRANTEE_USER_ID_SIZE 128
/**
* This is the maximum number of characters (including terminating \0) that
* libs3 supports in an ACL grantee user display name.
**/
#define S3_MAX_GRANTEE_DISPLAY_NAME_SIZE 128
/**
* This is the maximum number of characters that will be stored in the
* return buffer for the utility function which computes an HTTP authenticated
* query string
**/
#define S3_MAX_AUTHENTICATED_QUERY_STRING_SIZE \
(sizeof("https:///") + S3_MAX_HOSTNAME_SIZE + (S3_MAX_KEY_SIZE * 3) + \
sizeof("?AWSAccessKeyId=") + 32 + sizeof("&Expires=") + 32 + \
sizeof("&Signature=") + 28 + 1)
/**
* This constant is used by the S3_initialize() function, to specify that
* the winsock library should be initialized by libs3; only relevent on
* Microsoft Windows platforms.
**/
#define S3_INIT_WINSOCK 1
/**
* This convenience constant is used by the S3_initialize() function to
* indicate that all libraries required by libs3 should be initialized.
**/
#define S3_INIT_ALL (S3_INIT_WINSOCK)
/** **************************************************************************
* Enumerations
************************************************************************** **/
/**
* S3Status is a status code as returned by a libs3 function. The meaning of
* each status code is defined in the comments for each function which returns
* that status.
**/
typedef enum
{
S3StatusOK ,
/**
* Errors that prevent the S3 request from being issued or response from
* being read
**/
S3StatusInternalError ,
S3StatusOutOfMemory ,
S3StatusInterrupted ,
S3StatusInvalidBucketNameTooLong ,
S3StatusInvalidBucketNameFirstCharacter ,
S3StatusInvalidBucketNameCharacter ,
S3StatusInvalidBucketNameCharacterSequence ,
S3StatusInvalidBucketNameTooShort ,
S3StatusInvalidBucketNameDotQuadNotation ,
S3StatusQueryParamsTooLong ,
S3StatusFailedToInitializeRequest ,
S3StatusMetaDataHeadersTooLong ,
S3StatusBadMetaData ,
S3StatusBadContentType ,
S3StatusContentTypeTooLong ,
S3StatusBadMD5 ,
S3StatusMD5TooLong ,
S3StatusBadCacheControl ,
S3StatusCacheControlTooLong ,
S3StatusBadContentDispositionFilename ,
S3StatusContentDispositionFilenameTooLong ,
S3StatusBadContentEncoding ,
S3StatusContentEncodingTooLong ,
S3StatusBadIfMatchETag ,
S3StatusIfMatchETagTooLong ,
S3StatusBadIfNotMatchETag ,
S3StatusIfNotMatchETagTooLong ,
S3StatusHeadersTooLong ,
S3StatusKeyTooLong ,
S3StatusUriTooLong ,
S3StatusXmlParseFailure ,
S3StatusEmailAddressTooLong ,
S3StatusUserIdTooLong ,
S3StatusUserDisplayNameTooLong ,
S3StatusGroupUriTooLong ,
S3StatusPermissionTooLong ,
S3StatusTargetBucketTooLong ,
S3StatusTargetPrefixTooLong ,
S3StatusTooManyGrants ,
S3StatusBadGrantee ,
S3StatusBadPermission ,
S3StatusXmlDocumentTooLarge ,
S3StatusNameLookupError ,
S3StatusFailedToConnect ,
S3StatusServerFailedVerification ,
S3StatusConnectionFailed ,
S3StatusAbortedByCallback ,
/**
* Errors from the S3 service
**/
S3StatusErrorAccessDenied ,
S3StatusErrorAccountProblem ,
S3StatusErrorAmbiguousGrantByEmailAddress ,
S3StatusErrorBadDigest ,
S3StatusErrorBucketAlreadyExists ,
S3StatusErrorBucketAlreadyOwnedByYou ,
S3StatusErrorBucketNotEmpty ,
S3StatusErrorCredentialsNotSupported ,
S3StatusErrorCrossLocationLoggingProhibited ,
S3StatusErrorEntityTooSmall ,
S3StatusErrorEntityTooLarge ,
S3StatusErrorExpiredToken ,
S3StatusErrorIncompleteBody ,
S3StatusErrorIncorrectNumberOfFilesInPostRequest ,
S3StatusErrorInlineDataTooLarge ,
S3StatusErrorInternalError ,
S3StatusErrorInvalidAccessKeyId ,
S3StatusErrorInvalidAddressingHeader ,
S3StatusErrorInvalidArgument ,
S3StatusErrorInvalidBucketName ,
S3StatusErrorInvalidDigest ,
S3StatusErrorInvalidLocationConstraint ,
S3StatusErrorInvalidPayer ,
S3StatusErrorInvalidPolicyDocument ,
S3StatusErrorInvalidRange ,
S3StatusErrorInvalidSecurity ,
S3StatusErrorInvalidSOAPRequest ,
S3StatusErrorInvalidStorageClass ,
S3StatusErrorInvalidTargetBucketForLogging ,
S3StatusErrorInvalidToken ,
S3StatusErrorInvalidURI ,
S3StatusErrorKeyTooLong ,
S3StatusErrorMalformedACLError ,
S3StatusErrorMalformedXML ,
S3StatusErrorMaxMessageLengthExceeded ,
S3StatusErrorMaxPostPreDataLengthExceededError ,
S3StatusErrorMetadataTooLarge ,
S3StatusErrorMethodNotAllowed ,
S3StatusErrorMissingAttachment ,
S3StatusErrorMissingContentLength ,
S3StatusErrorMissingSecurityElement ,
S3StatusErrorMissingSecurityHeader ,
S3StatusErrorNoLoggingStatusForKey ,
S3StatusErrorNoSuchBucket ,
S3StatusErrorNoSuchKey ,
S3StatusErrorNotImplemented ,
S3StatusErrorNotSignedUp ,
S3StatusErrorOperationAborted ,
S3StatusErrorPermanentRedirect ,
S3StatusErrorPreconditionFailed ,
S3StatusErrorRedirect ,
S3StatusErrorRequestIsNotMultiPartContent ,
S3StatusErrorRequestTimeout ,
S3StatusErrorRequestTimeTooSkewed ,
S3StatusErrorRequestTorrentOfBucketError ,
S3StatusErrorSignatureDoesNotMatch ,
S3StatusErrorSlowDown ,
S3StatusErrorTemporaryRedirect ,
S3StatusErrorTokenRefreshRequired ,
S3StatusErrorTooManyBuckets ,
S3StatusErrorUnexpectedContent ,
S3StatusErrorUnresolvableGrantByEmailAddress ,
S3StatusErrorUserKeyMustBeSpecified ,
S3StatusErrorUnknown ,
/**
* The following are HTTP errors returned by S3 without enough detail to
* distinguish any of the above S3StatusError conditions
**/
S3StatusHttpErrorMovedTemporarily ,
S3StatusHttpErrorBadRequest ,
S3StatusHttpErrorForbidden ,
S3StatusHttpErrorNotFound ,
S3StatusHttpErrorConflict ,
S3StatusHttpErrorUnknown
} S3Status;
/**
* S3Protocol represents a protocol that may be used for communicating a
* request to the Amazon S3 service.
*
* In general, HTTPS is greatly preferred (and should be the default of any
* application using libs3) because it protects any data being sent to or
* from S3 using strong encryption. However, HTTPS is much more CPU intensive
* than HTTP, and if the caller is absolutely certain that it is OK for the
* data to be viewable by anyone in transit, then HTTP can be used.
**/
typedef enum
{
S3ProtocolHTTPS = 0,
S3ProtocolHTTP = 1
} S3Protocol;
/**
* S3UriStyle defines the form that an Amazon S3 URI identifying a bucket or
* object can take. They are of these forms:
*
* Virtual Host: ${protocol}://${bucket}.s3.amazonaws.com/[${key}]
* Path: ${protocol}://s3.amazonaws.com/${bucket}/[${key}]
*
* It is generally better to use the Virual Host URI form, because it ensures
* that the bucket name used is compatible with normal HTTP GETs and POSTs of
* data to/from the bucket. However, if DNS lookups for the bucket are too
* slow or unreliable for some reason, Path URI form may be used.
**/
typedef enum
{
S3UriStyleVirtualHost = 0,
S3UriStylePath = 1
} S3UriStyle;
/**
* S3GranteeType defines the type of Grantee used in an S3 ACL Grant.
* Amazon Customer By Email - identifies the Grantee using their Amazon S3
* account email address
* Canonical User - identifies the Grantee by S3 User ID and Display Name,
* which can only be obtained by making requests to S3, for example, by
* listing owned buckets
* All AWS Users - identifies all authenticated AWS users
* All Users - identifies all users
* Log Delivery - identifies the Amazon group responsible for writing
* server access logs into buckets
**/
typedef enum
{
S3GranteeTypeAmazonCustomerByEmail = 0,
S3GranteeTypeCanonicalUser = 1,
S3GranteeTypeAllAwsUsers = 2,
S3GranteeTypeAllUsers = 3,
S3GranteeTypeLogDelivery = 4
} S3GranteeType;
/**
* This is an individual permission granted to a grantee in an S3 ACL Grant.
* Read permission gives the Grantee the permission to list the bucket, or
* read the object or its metadata
* Write permission gives the Grantee the permission to create, overwrite, or
* delete any object in the bucket, and is not supported for objects
* ReadACP permission gives the Grantee the permission to read the ACP for
* the bucket or object; the owner of the bucket or object always has
* this permission implicitly
* WriteACP permission gives the Grantee the permission to overwrite the ACP
* for the bucket or object; the owner of the bucket or object always has
* this permission implicitly
* FullControl permission gives the Grantee all permissions specified by the
* Read, Write, ReadACP, and WriteACP permissions
**/
typedef enum
{
S3PermissionRead = 0,
S3PermissionWrite = 1,
S3PermissionReadACP = 2,
S3PermissionWriteACP = 3,
S3PermissionFullControl = 4
} S3Permission;
/**
* S3CannedAcl is an ACL that can be specified when an object is created or
* updated. Each canned ACL has a predefined value when expanded to a full
* set of S3 ACL Grants.
* Private canned ACL gives the owner FULL_CONTROL and no other permissions
* are issued
* Public Read canned ACL gives the owner FULL_CONTROL and all users Read
* permission
* Public Read Write canned ACL gives the owner FULL_CONTROL and all users
* Read and Write permission
* AuthenticatedRead canned ACL gives the owner FULL_CONTROL and authenticated
* S3 users Read permission
**/
typedef enum
{
S3CannedAclPrivate = 0, /* private */
S3CannedAclPublicRead = 1, /* public-read */
S3CannedAclPublicReadWrite = 2, /* public-read-write */
S3CannedAclAuthenticatedRead = 3 /* authenticated-read */
} S3CannedAcl;
/** **************************************************************************
* Data Types
************************************************************************** **/
/**
* An S3RequestContext manages multiple S3 requests simultaneously; see the
* S3_XXX_request_context functions below for details
**/
typedef struct S3RequestContext S3RequestContext;
/**
* S3NameValue represents a single Name - Value pair, used to represent either
* S3 metadata associated with a key, or S3 error details.
**/
typedef struct S3NameValue
{
/**
* The name part of the Name - Value pair
**/
const char *name;
/**
* The value part of the Name - Value pair
**/
const char *value;
} S3NameValue;
/**
* S3ResponseProperties is passed to the properties callback function which is
* called when the complete response properties have been received. Some of
* the fields of this structure are optional and may not be provided in the
* response, and some will always be provided in the response.
**/
typedef struct S3ResponseProperties
{
/**
* This optional field identifies the request ID and may be used when
* reporting problems to Amazon.
**/
const char *requestId;
/**
* This optional field identifies the request ID and may be used when
* reporting problems to Amazon.
**/
const char *requestId2;
/**
* This optional field is the content type of the data which is returned
* by the request. If not provided, the default can be assumed to be
* "binary/octet-stream".
**/
const char *contentType;
/**
* This optional field is the content length of the data which is returned
* in the response. A negative value means that this value was not
* provided in the response. A value of 0 means that there is no content
* provided. A positive value gives the number of bytes in the content of
* the response.
**/
uint64_t contentLength;
/**
* This optional field names the server which serviced the request.
**/
const char *server;
/**
* This optional field provides a string identifying the unique contents
* of the resource identified by the request, such that the contents can
* be assumed not to be changed if the same eTag is returned at a later
* time decribing the same resource. This is an MD5 sum of the contents.
**/
const char *eTag;
/**
* This optional field provides the last modified time, relative to the
* Unix epoch, of the contents. If this value is < 0, then the last
* modified time was not provided in the response. If this value is >= 0,
* then the last modified date of the contents are available as a number
* of seconds since the UNIX epoch.
*
**/
int64_t lastModified;
/**
* This is the number of user-provided meta data associated with the
* resource.
**/
int metaDataCount;
/**
* These are the meta data associated with the resource. In each case,
* the name will not include any S3-specific header prefixes
* (i.e. x-amz-meta- will have been removed from the beginning), and
* leading and trailing whitespace will have been stripped from the value.
**/
const S3NameValue *metaData;
} S3ResponseProperties;
/**
* S3AclGrant identifies a single grant in the ACL for a bucket or object. An
* ACL is composed of any number of grants, which specify a grantee and the
* permissions given to that grantee. S3 does not normalize ACLs in any way,
* so a redundant ACL specification will lead to a redundant ACL stored in S3.
**/
typedef struct S3AclGrant
{
/**
* The granteeType gives the type of grantee specified by this grant.
**/
S3GranteeType granteeType;
/**
* The identifier of the grantee that is set is determined by the
* granteeType:
*
* S3GranteeTypeAmazonCustomerByEmail - amazonCustomerByEmail.emailAddress
* S3GranteeTypeCanonicalUser - canonicalUser.id, canonicalUser.displayName
* S3GranteeTypeAllAwsUsers - none
* S3GranteeTypeAllUsers - none
**/
union
{
/**
* This structure is used iff the granteeType is
* S3GranteeTypeAmazonCustomerByEmail.
**/
struct
{
/**
* This is the email address of the Amazon Customer being granted
* permissions by this S3AclGrant.
**/
char emailAddress[S3_MAX_GRANTEE_EMAIL_ADDRESS_SIZE];
} amazonCustomerByEmail;
/**
* This structure is used iff the granteeType is
* S3GranteeTypeCanonicalUser.
**/
struct
{
/**
* This is the CanonicalUser ID of the grantee
**/
char id[S3_MAX_GRANTEE_USER_ID_SIZE];
/**
* This is the display name of the grantee
**/
char displayName[S3_MAX_GRANTEE_DISPLAY_NAME_SIZE];
} canonicalUser;
} grantee;
/**
* This is the S3Permission to be granted to the grantee
**/
S3Permission permission;
} S3AclGrant;
/**
* A context for working with objects within a bucket. A bucket context holds
* all information necessary for working with a bucket, and may be used
* repeatedly over many consecutive (or simultaneous) calls into libs3 bucket
* operation functions.
**/
typedef struct S3BucketContext
{
/**
* The name of the host to connect to when making S3 requests. If set to
* NULL, the default S3 hostname passed in to S3_initialize will be used.
**/
const char *hostName;
/**
* The name of the bucket to use in the bucket context
**/
const char *bucketName;
/**
* The protocol to use when accessing the bucket
**/
S3Protocol protocol;
/**
* The URI style to use for all URIs sent to Amazon S3 while working with
* this bucket context
**/
S3UriStyle uriStyle;
/**
* The Amazon Access Key ID to use for access to the bucket
**/
const char *accessKeyId;
/**
* The Amazon Secret Access Key to use for access to the bucket
**/
const char *secretAccessKey;
} S3BucketContext;
/**
* This is a single entry supplied to the list bucket callback by a call to
* S3_list_bucket. It identifies a single matching key from the list
* operation.
**/
typedef struct S3ListBucketContent
{
/**
* This is the next key in the list bucket results.
**/
const char *key;
/**
* This is the number of seconds since UNIX epoch of the last modified
* date of the object identified by the key.
**/
int64_t lastModified;
/**
* This gives a tag which gives a signature of the contents of the object,
* which is the MD5 of the contents of the object.
**/
const char *eTag;
/**
* This is the size of the object in bytes.
**/
uint64_t size;
/**
* This is the ID of the owner of the key; it is present only if access
* permissions allow it to be viewed.
**/
const char *ownerId;
/**
* This is the display name of the owner of the key; it is present only if
* access permissions allow it to be viewed.
**/
const char *ownerDisplayName;
} S3ListBucketContent;
/**
* S3PutProperties is the set of properties that may optionally be set by the
* user when putting objects to S3. Each field of this structure is optional
* and may or may not be present.
**/
typedef struct S3PutProperties
{
/**
* If present, this is the Content-Type that should be associated with the
* object. If not provided, S3 defaults to "binary/octet-stream".
**/
const char *contentType;
/**
* If present, this provides the MD5 signature of the contents, and is
* used to validate the contents. This is highly recommended by Amazon
* but not required. Its format is as a base64-encoded MD5 sum.
**/
const char *md5;
/**
* If present, this gives a Cache-Control header string to be supplied to
* HTTP clients which download this
**/
const char *cacheControl;
/**
* If present, this gives the filename to save the downloaded file to,
* whenever the object is downloaded via a web browser. This is only
* relevent for objects which are intended to be shared to users via web
* browsers and which is additionally intended to be downloaded rather
* than viewed.
**/
const char *contentDispositionFilename;
/**
* If present, this identifies the content encoding of the object. This
* is only applicable to encoded (usually, compressed) content, and only
* relevent if the object is intended to be downloaded via a browser.
**/
const char *contentEncoding;
/**
* If >= 0, this gives an expiration date for the content. This
* information is typically only delivered to users who download the
* content via a web browser.
**/
int64_t expires;
/**
* This identifies the "canned ACL" that should be used for this object.
* The default (0) gives only the owner of the object access to it.
**/
S3CannedAcl cannedAcl;
/**
* This is the number of values in the metaData field.
**/
int metaDataCount;
/**
* These are the meta data to pass to S3. In each case, the name part of
* the Name - Value pair should not include any special S3 HTTP header
* prefix (i.e., should be of the form 'foo', NOT 'x-amz-meta-foo').
**/
const S3NameValue *metaData;
} S3PutProperties;
/**
* S3GetConditions is used for the get_object operation, and specifies
* conditions which the object must meet in order to be successfully returned.
**/
typedef struct S3GetConditions
{
/**
* The request will be processed if the Last-Modification header of the
* object is greater than or equal to this value, specified as a number of
* seconds since Unix epoch. If this value is less than zero, it will not
* be used in the conditional.
**/
int64_t ifModifiedSince;
/**
* The request will be processed if the Last-Modification header of the
* object is less than this value, specified as a number of seconds since
* Unix epoch. If this value is less than zero, it will not be used in
* the conditional.
**/
int64_t ifNotModifiedSince;
/**
* If non-NULL, this gives an eTag header value which the object must
* match in order to be returned. Note that altough the eTag is simply an
* MD5, this must be presented in the S3 eTag form, which typically
* includes double-quotes.
**/
const char *ifMatchETag;
/**
* If non-NULL, this gives an eTag header value which the object must not
* match in order to be returned. Note that altough the eTag is simply an
* MD5, this must be presented in the S3 eTag form, which typically
* includes double-quotes.
**/
const char *ifNotMatchETag;
} S3GetConditions;
/**
* S3ErrorDetails provides detailed information describing an S3 error. This
* is only presented when the error is an S3-generated error (i.e. one of the
* S3StatusErrorXXX values).
**/
typedef struct S3ErrorDetails
{
/**
* This is the human-readable message that Amazon supplied describing the
* error
**/
const char *message;
/**
* This identifies the resource for which the error occurred
**/
const char *resource;
/**
* This gives human-readable further details describing the specifics of
* this error
**/
const char *furtherDetails;
/**
* This gives the number of S3NameValue pairs present in the extraDetails
* array
**/
int extraDetailsCount;
/**
* S3 can provide extra details in a freeform Name - Value pair format.
* Each error can have any number of these, and this array provides these
* additional extra details.
**/
S3NameValue *extraDetails;
} S3ErrorDetails;
/** **************************************************************************
* Callback Signatures
************************************************************************** **/
/**
* This callback is made whenever the response properties become available for
* any request.
*
* @param properties are the properties that are available from the response
* @param callbackData is the callback data as specified when the request
* was issued.
* @return S3StatusOK to continue processing the request, anything else to
* immediately abort the request with a status which will be
* passed to the S3ResponseCompleteCallback for this request.
* Typically, this will return either S3StatusOK or
* S3StatusAbortedByCallback.
**/
typedef S3Status (S3ResponsePropertiesCallback)
(const S3ResponseProperties *properties, void *callbackData);
/**
* This callback is made when the response has been completely received, or an
* error has occurred which has prematurely aborted the request, or one of the
* other user-supplied callbacks returned a value intended to abort the
* request. This callback is always made for every request, as the very last
* callback made for that request.
*
* @param status gives the overall status of the response, indicating success
* or failure; use S3_status_is_retryable() as a simple way to detect
* whether or not the status indicates that the request failed but may
* be retried.
* @param errorDetails if non-NULL, gives details as returned by the S3
* service, describing the error
* @param callbackData is the callback data as specified when the request
* was issued.
**/
typedef void (S3ResponseCompleteCallback)(S3Status status,
const S3ErrorDetails *errorDetails,
void *callbackData);
/**
* This callback is made for each bucket resulting from a list service
* operation.
*
* @param ownerId is the ID of the owner of the bucket
* @param ownerDisplayName is the owner display name of the owner of the bucket
* @param bucketName is the name of the bucket
* @param creationDateSeconds if < 0 indicates that no creation date was
* supplied for the bucket; if >= 0 indicates the number of seconds
* since UNIX Epoch of the creation date of the bucket
* @param callbackData is the callback data as specified when the request
* was issued.
* @return S3StatusOK to continue processing the request, anything else to
* immediately abort the request with a status which will be
* passed to the S3ResponseCompleteCallback for this request.
* Typically, this will return either S3StatusOK or
* S3StatusAbortedByCallback.
**/
typedef S3Status (S3ListServiceCallback)(const char *ownerId,
const char *ownerDisplayName,
const char *bucketName,
int64_t creationDateSeconds,
void *callbackData);
/**
* This callback is made repeatedly as a list bucket operation progresses.
* The contents reported via this callback are only reported once per list
* bucket operation, but multiple calls to this callback may be necessary to
* report all items resulting from the list bucket operation.
*
* @param isTruncated is true if the list bucket request was truncated by the
* S3 service, in which case the remainder of the list may be obtained
* by querying again using the Marker parameter to start the query
* after this set of results
* @param nextMarker if present, gives the largest (alphabetically) key
* returned in the response, which, if isTruncated is true, may be used
* as the marker in a subsequent list buckets operation to continue
* listing
* @param contentsCount is the number of ListBucketContent structures in the
* contents parameter
* @param contents is an array of ListBucketContent structures, each one
* describing an object in the bucket
* @param commonPrefixesCount is the number of common prefixes strings in the
* commonPrefixes parameter
* @param commonPrefixes is an array of strings, each specifing one of the
* common prefixes as returned by S3
* @param callbackData is the callback data as specified when the request
* was issued.
* @return S3StatusOK to continue processing the request, anything else to
* immediately abort the request with a status which will be
* passed to the S3ResponseCompleteCallback for this request.
* Typically, this will return either S3StatusOK or
* S3StatusAbortedByCallback.
**/
typedef S3Status (S3ListBucketCallback)(int isTruncated,
const char *nextMarker,
int contentsCount,
const S3ListBucketContent *contents,
int commonPrefixesCount,
const char **commonPrefixes,
void *callbackData);
/**
* This callback is made during a put object operation, to obtain the next
* chunk of data to put to the S3 service as the contents of the object. This
* callback is made repeatedly, each time acquiring the next chunk of data to
* write to the service, until a negative or 0 value is returned.
*
* @param bufferSize gives the maximum number of bytes that may be written
* into the buffer parameter by this callback
* @param buffer gives the buffer to fill with at most bufferSize bytes of
* data as the next chunk of data to send to S3 as the contents of this
* object
* @param callbackData is the callback data as specified when the request
* was issued.
* @return < 0 to abort the request with the S3StatusAbortedByCallback, which
* will be pased to the response complete callback for this request, or
* 0 to indicate the end of data, or > 0 to identify the number of
* bytes that were written into the buffer by this callback
**/
typedef int (S3PutObjectDataCallback)(int bufferSize, char *buffer,
void *callbackData);
/**
* This callback is made during a get object operation, to provide the next
* chunk of data available from the S3 service constituting the contents of
* the object being fetched. This callback is made repeatedly, each time
* providing the next chunk of data read, until the complete object contents
* have been passed through the callback in this way, or the callback
* returns an error status.
*
* @param bufferSize gives the number of bytes in buffer
* @param buffer is the data being passed into the callback
* @param callbackData is the callback data as specified when the request
* was issued.
* @return S3StatusOK to continue processing the request, anything else to
* immediately abort the request with a status which will be
* passed to the S3ResponseCompleteCallback for this request.
* Typically, this will return either S3StatusOK or
* S3StatusAbortedByCallback.
**/
typedef S3Status (S3GetObjectDataCallback)(int bufferSize, const char *buffer,
void *callbackData);
/** **************************************************************************
* Callback Structures
************************************************************************** **/
/**
* An S3ResponseHandler defines the callbacks which are made for any
* request.
**/
typedef struct S3ResponseHandler
{
/**
* The propertiesCallback is made when the response properties have
* successfully been returned from S3. This function may not be called
* if the response properties were not successfully returned from S3.
**/
S3ResponsePropertiesCallback *propertiesCallback;
/**
* The completeCallback is always called for every request made to S3,
* regardless of the outcome of the request. It provides the status of
* the request upon its completion, as well as extra error details in the
* event of an S3 error.
**/
S3ResponseCompleteCallback *completeCallback;
} S3ResponseHandler;
/**
* An S3ListServiceHandler defines the callbacks which are made for
* list_service requests.
**/
typedef struct S3ListServiceHandler
{
/**
* responseHandler provides the properties and complete callback
**/
S3ResponseHandler responseHandler;
/**
* The listServiceCallback is called as items are reported back from S3 as
* responses to the request
**/
S3ListServiceCallback *listServiceCallback;
} S3ListServiceHandler;
/**
* An S3ListBucketHandler defines the callbacks which are made for
* list_bucket requests.
**/
typedef struct S3ListBucketHandler
{
/**
* responseHandler provides the properties and complete callback
**/
S3ResponseHandler responseHandler;
/**
* The listBucketCallback is called as items are reported back from S3 as
* responses to the request. This may be called more than one time per
* list bucket request, each time providing more items from the list
* operation.
**/
S3ListBucketCallback *listBucketCallback;
} S3ListBucketHandler;
/**
* An S3PutObjectHandler defines the callbacks which are made for
* put_object requests.
**/
typedef struct S3PutObjectHandler
{
/**
* responseHandler provides the properties and complete callback
**/
S3ResponseHandler responseHandler;
/**
* The putObjectDataCallback is called to acquire data to send to S3 as
* the contents of the put_object request. It is made repeatedly until it
* returns a negative number (indicating that the request should be
* aborted), or 0 (indicating that all data has been supplied).
**/
S3PutObjectDataCallback *putObjectDataCallback;
} S3PutObjectHandler;
/**
* An S3GetObjectHandler defines the callbacks which are made for
* get_object requests.
**/
typedef struct S3GetObjectHandler
{
/**
* responseHandler provides the properties and complete callback
**/
S3ResponseHandler responseHandler;
/**
* The getObjectDataCallback is called as data is read from S3 as the
* contents of the object being read in the get_object request. It is
* called repeatedly until there is no more data provided in the request,
* or until the callback returns an error status indicating that the
* request should be aborted.
**/
S3GetObjectDataCallback *getObjectDataCallback;
} S3GetObjectHandler;
/** **************************************************************************
* General Library Functions
************************************************************************** **/
/**
* Initializes libs3 for use. This function must be called before any other
* libs3 function is called. It may be called multiple times, with the same
* effect as calling it once, as long as S3_deinitialize() is called an
* equal number of times when the program has finished. This function is NOT
* thread-safe and must only be called by one thread at a time.
*
* @param userAgentInfo is a string that will be included in the User-Agent
* header of every request made to the S3 service. You may provide
* NULL or the empty string if you don't care about this. The value
* will not be copied by this function and must remain unaltered by the
* caller until S3_deinitialize() is called.
* @param flags is a bitmask of some combination of S3_INIT_XXX flag, or
* S3_INIT_ALL, indicating which of the libraries that libs3 depends
* upon should be initialized by S3_initialize(). Only if your program
* initializes one of these dependency libraries itself should anything
* other than S3_INIT_ALL be passed in for this bitmask.
*
* You should pass S3_INIT_WINSOCK if and only if your application does
* not initialize winsock elsewhere. On non-Microsoft Windows
* platforms it has no effect.
*
* As a convenience, the macro S3_INIT_ALL is provided, which will do
* all necessary initialization; however, be warned that things may
* break if your application re-initializes the dependent libraries
* later.
* @param defaultS3Hostname is a string the specifies the default S3 server
* hostname to use when making S3 requests; this value is used
* whenever the hostName of an S3BucketContext is NULL. If NULL is
* passed here then the default of S3_DEFAULT_HOSTNAME will be used.
* @return One of:
* S3StatusOK on success
* S3StatusUriTooLong if the defaultS3HostName is longer than
* S3_MAX_HOSTNAME_SIZE
* S3StatusInternalError if dependent libraries could not be
* initialized
* S3StatusOutOfMemory on failure due to out of memory
**/
S3Status S3_initialize(const char *userAgentInfo, int flags,
const char *defaultS3HostName);
/**
* Must be called once per program for each call to libs3_initialize(). After
* this call is complete, no libs3 function may be called except
* S3_initialize().
**/
void S3_deinitialize();
/**
* Returns a string with the textual name of an S3Status code
*
* @param status is S3Status code for which the textual name will be returned
* @return a string with the textual name of an S3Status code
**/
const char *S3_get_status_name(S3Status status);
/**
* This function may be used to validate an S3 bucket name as being in the
* correct form for use with the S3 service. Amazon S3 limits the allowed
* characters in S3 bucket names, as well as imposing some additional rules on
* the length of bucket names and their structure. There are actually two
* limits; one for bucket names used only in path-style URIs, and a more
* strict limit used for bucket names used in virtual-host-style URIs. It is
* advisable to use only bucket names which meet the more strict requirements
* regardless of how the bucket expected to be used.
*
* This method does NOT validate that the bucket is available for use in the
* S3 service, so the return value of this function cannot be used to decide
* whether or not a bucket with the give name already exists in Amazon S3 or
* is accessible by the caller. It merely validates that the bucket name is
* valid for use with S3.
*
* @param bucketName is the bucket name to validate
* @param uriStyle gives the URI style to validate the bucket name against.
* It is advisable to always use S3UriStyleVirtuallHost.
* @return One of:
* S3StatusOK if the bucket name was validates successfully
* S3StatusInvalidBucketNameTooLong if the bucket name exceeded the
* length limitation for the URI style, which is 255 bytes for
* path style URIs and 63 bytes for virtual host type URIs
* S3StatusInvalidBucketNameTooShort if the bucket name is less than
* 3 characters
* S3StatusInvalidBucketNameFirstCharacter if the bucket name as an
* invalid first character, which is anything other than
* an alphanumeric character
* S3StatusInvalidBucketNameCharacterSequence if the bucket name
* includes an invalid character sequence, which for virtual host
* style buckets is ".-" or "-."
* S3StatusInvalidBucketNameCharacter if the bucket name includes an
* invalid character, which is anything other than alphanumeric,
* '-', '.', or for path style URIs only, '_'.
* S3StatusInvalidBucketNameDotQuadNotation if the bucket name is in
* dot-quad notation, i.e. the form of an IP address, which is
* not allowed by Amazon S3.
**/
S3Status S3_validate_bucket_name(const char *bucketName, S3UriStyle uriStyle);
/**
* Converts an XML representation of an ACL to a libs3 structured
* representation. This method is not strictly necessary for working with
* ACLs using libs3, but may be convenient for users of the library who read
* ACLs from elsewhere in XML format and need to use these ACLs with libs3.
*
* @param aclXml is the XML representation of the ACL. This must be a
* zero-terminated character string.
* @param ownerId will be filled in with the Owner ID specified in the XML.
* At most MAX_GRANTEE_USER_ID_SIZE bytes will be stored at this
* location.
* @param ownerDisplayName will be filled in with the Owner Display Name
* specified in the XML. At most MAX_GRANTEE_DISPLAY_NAME_SIZE bytes
* will be stored at this location.
* @param aclGrantCountReturn returns the number of S3AclGrant structures
* returned in the aclGrantsReturned array
* @param aclGrants must be passed in as an array of at least S3_ACL_MAXCOUNT
* structures, and on return from this function, the first
* aclGrantCountReturn structures will be filled in with the ACLs
* represented by the input XML.
* @return One of:
* S3StatusOK on successful conversion of the ACL
* S3StatusInternalError on internal error representing a bug in the
* libs3 library
* S3StatusXmlParseFailure if the XML document was malformed
**/
S3Status S3_convert_acl(char *aclXml, char *ownerId, char *ownerDisplayName,
int *aclGrantCountReturn, S3AclGrant *aclGrants);
/**
* Returns nonzero if the status indicates that the request should be
* immediately retried, because the status indicates an error of a nature that
* is likely due to transient conditions on the local system or S3, such as
* network failures, or internal retryable errors reported by S3. Returns
* zero otherwise.
*
* @param status is the status to evaluate
* @return nonzero if the status indicates a retryable error, 0 otherwise
**/
int S3_status_is_retryable(S3Status status);
/** **************************************************************************
* Request Context Management Functions
************************************************************************** **/
/**
* An S3RequestContext allows muliple requests to be serviced by the same
* thread simultaneously. It is an optional parameter to all libs3 request
* functions, and if provided, the request is managed by the S3RequestContext;
* if not, the request is handled synchronously and is complete when the libs3
* request function has returned.
*
* @param requestContextReturn returns the newly-created S3RequestContext
* structure, which if successfully returned, must be destroyed via a
* call to S3_destroy_request_context when it is no longer needed. If
* an error status is returned from this function, then
* requestContextReturn will not have been filled in, and
* S3_destroy_request_context should not be called on it
* @return One of:
* S3StatusOK if the request context was successfully created
* S3StatusOutOfMemory if the request context could not be created due
* to an out of memory error
**/
S3Status S3_create_request_context(S3RequestContext **requestContextReturn);
/**
* Destroys an S3RequestContext which was created with
* S3_create_request_context. Any requests which are currently being
* processed by the S3RequestContext will immediately be aborted and their
* request completed callbacks made with the status S3StatusInterrupted.
*
* @param requestContext is the S3RequestContext to destroy
**/
void S3_destroy_request_context(S3RequestContext *requestContext);
/**
* Runs the S3RequestContext until all requests within it have completed,
* or until an error occurs.
*
* @param requestContext is the S3RequestContext to run until all requests
* within it have completed or until an error occurs
* @return One of:
* S3Status if all requests were successfully run to completion
* S3StatusInternalError if an internal error prevented the
* S3RequestContext from running one or more requests
* S3StatusOutOfMemory if requests could not be run to completion
* due to an out of memory error
**/
S3Status S3_runall_request_context(S3RequestContext *requestContext);
/**
* Does some processing of requests within the S3RequestContext. One or more
* requests may have callbacks made on them and may complete. This function
* processes any requests which have immediately available I/O, and will not
* block waiting for I/O on any request. This function would normally be used
* with S3_get_request_context_fdsets.
*
* @param requestContext is the S3RequestContext to process
* @param requestsRemainingReturn returns the number of requests remaining
* and not yet completed within the S3RequestContext after this
* function returns.
* @return One of:
* S3StatusOK if request processing proceeded without error
* S3StatusInternalError if an internal error prevented the
* S3RequestContext from running one or more requests
* S3StatusOutOfMemory if requests could not be processed due to
* an out of memory error
**/
S3Status S3_runonce_request_context(S3RequestContext *requestContext,
int *requestsRemainingReturn);
/**
* This function, in conjunction allows callers to manually manage a set of
* requests using an S3RequestContext. This function returns the set of file
* descriptors which the caller can watch (typically using select()), along
* with any other file descriptors of interest to the caller, and using
* whatever timeout (if any) the caller wishes, until one or more file
* descriptors in the returned sets become ready for I/O, at which point
* S3_runonce_request_context can be called to process requests with available
* I/O.
*
* @param requestContext is the S3RequestContext to get fd_sets from
* @param readFdSet is a pointer to an fd_set which will have all file
* descriptors to watch for read events for the requests in the
* S3RequestContext set into it upon return. Should be zero'd out
* (using FD_ZERO) before being passed into this function.
* @param writeFdSet is a pointer to an fd_set which will have all file
* descriptors to watch for write events for the requests in the
* S3RequestContext set into it upon return. Should be zero'd out
* (using FD_ZERO) before being passed into this function.
* @param exceptFdSet is a pointer to an fd_set which will have all file
* descriptors to watch for exception events for the requests in the
* S3RequestContext set into it upon return. Should be zero'd out
* (using FD_ZERO) before being passed into this function.
* @param maxFd returns the highest file descriptor set into any of the
* fd_sets, or -1 if no file descriptors were set
* @return One of:
* S3StatusOK if all fd_sets were successfully set
* S3StatusInternalError if an internal error prevented this function
* from completing successfully
**/
S3Status S3_get_request_context_fdsets(S3RequestContext *requestContext,
fd_set *readFdSet, fd_set *writeFdSet,
fd_set *exceptFdSet, int *maxFd);
/**
* This function returns the maximum number of milliseconds that the caller of
* S3_runonce_request_context should wait on the fdsets obtained via a call to
* S3_get_request_context_fdsets. In other words, this is essentially the
* select() timeout that needs to be used (shorter values are OK, but no
* longer than this) to ensure that internal timeout code of libs3 can work
* properly. This function should be called right before select() each time
* select() on the request_context fdsets are to be performed by the libs3
* user.
*
* @param requestContext is the S3RequestContext to get the timeout from
* @return the maximum number of milliseconds to select() on fdsets. Callers
* could wait a shorter time if they wish, but not longer.
**/
int64_t S3_get_request_context_timeout(S3RequestContext *requestContext);
/** **************************************************************************
* S3 Utility Functions
************************************************************************** **/
/**
* Generates an HTTP authenticated query string, which may then be used by
* a browser (or other web client) to issue the request. The request is
* implicitly a GET request; Amazon S3 is documented to only support this type
* of authenticated query string request.
*
* @param buffer is the output buffer for the authenticated query string.
* It must be at least S3_MAX_AUTHENTICATED_QUERY_STRING_SIZE bytes in
* length.
* @param bucketContext gives the bucket and associated parameters for the
* request to generate.
* @param key gives the key which the authenticated request will GET.
* @param expires gives the number of seconds since Unix epoch for the
* expiration date of the request; after this time, the request will
* no longer be valid. If this value is negative, the largest
* expiration date possible is used (currently, Jan 19, 2038).
* @param resource gives a sub-resource to be fetched for the request, or NULL
* for none. This should be of the form "?<resource>", i.e.
* "?torrent".
* @return One of:
* S3StatusUriTooLong if, due to an internal error, the generated URI
* is longer than S3_MAX_AUTHENTICATED_QUERY_STRING_SIZE bytes in
* length and thus will not fit into the supplied buffer
* S3StatusOK on success
**/
S3Status S3_generate_authenticated_query_string
(char *buffer, const S3BucketContext *bucketContext,
const char *key, int64_t expires, const char *resource);
/** **************************************************************************
* Service Functions
************************************************************************** **/
/**
* Lists all S3 buckets belonging to the access key id.
*
* @param protocol gives the protocol to use for this request
* @param accessKeyId gives the Amazon Access Key ID for which to list owned
* buckets
* @param secretAccessKey gives the Amazon Secret Access Key for which to list
* owned buckets
* @param hostName is the S3 host name to use; if NULL is passed in, the
* default S3 host as provided to S3_initialize() will be used.
* @param requestContext if non-NULL, gives the S3RequestContext to add this
* request to, and does not perform the request immediately. If NULL,
* performs the request immediately and synchronously.
* @param handler gives the callbacks to call as the request is processed and
* completed
* @param callbackData will be passed in as the callbackData parameter to
* all callbacks for this request
**/
void S3_list_service(S3Protocol protocol, const char *accessKeyId,
const char *secretAccessKey, const char *hostName,
S3RequestContext *requestContext,
const S3ListServiceHandler *handler,
void *callbackData);
/** **************************************************************************
* Bucket Functions
************************************************************************** **/
/**
* Tests the existence of an S3 bucket, additionally returning the bucket's
* location if it exists and is accessible.
*
* @param protocol gives the protocol to use for this request
* @param uriStyle gives the URI style to use for this request
* @param accessKeyId gives the Amazon Access Key ID for which to list owned
* buckets
* @param secretAccessKey gives the Amazon Secret Access Key for which to list
* owned buckets
* @param hostName is the S3 host name to use; if NULL is passed in, the
* default S3 host as provided to S3_initialize() will be used.
* @param bucketName is the bucket name to test
* @param locationConstraintReturnSize gives the number of bytes in the
* locationConstraintReturn parameter
* @param locationConstraintReturn provides the location into which to write
* the name of the location constraint naming the geographic location
* of the S3 bucket. This must have at least as many characters in it
* as specified by locationConstraintReturn, and should start out
* NULL-terminated. On successful completion of this request, this
* will be set to the name of the geographic location of S3 bucket, or
* will be left as a zero-length string if no location was available.
* @param requestContext if non-NULL, gives the S3RequestContext to add this
* request to, and does not perform the request immediately. If NULL,
* performs the request immediately and synchronously.
* @param handler gives the callbacks to call as the request is processed and
* completed
* @param callbackData will be passed in as the callbackData parameter to
* all callbacks for this request
**/
void S3_test_bucket(S3Protocol protocol, S3UriStyle uriStyle,
const char *accessKeyId, const char *secretAccessKey,
const char *hostName, const char *bucketName,
int locationConstraintReturnSize,
char *locationConstraintReturn,
S3RequestContext *requestContext,
const S3ResponseHandler *handler, void *callbackData);
/**
* Creates a new bucket.
*
* @param protocol gives the protocol to use for this request
* @param accessKeyId gives the Amazon Access Key ID for which to list owned
* buckets
* @param secretAccessKey gives the Amazon Secret Access Key for which to list
* owned buckets
* @param hostName is the S3 host name to use; if NULL is passed in, the
* default S3 host as provided to S3_initialize() will be used.
* @param bucketName is the name of the bucket to be created
* @param cannedAcl gives the "REST canned ACL" to use for the created bucket
* @param locationConstraint if non-NULL, gives the geographic location for
* the bucket to create.
* @param requestContext if non-NULL, gives the S3RequestContext to add this
* request to, and does not perform the request immediately. If NULL,
* performs the request immediately and synchronously.
* @param handler gives the callbacks to call as the request is processed and
* completed
* @param callbackData will be passed in as the callbackData parameter to
* all callbacks for this request
**/
void S3_create_bucket(S3Protocol protocol, const char *accessKeyId,
const char *secretAccessKey, const char *hostName,
const char *bucketName, S3CannedAcl cannedAcl,
const char *locationConstraint,
S3RequestContext *requestContext,
const S3ResponseHandler *handler, void *callbackData);
/**
* Deletes a bucket. The bucket must be empty, or the status
* S3StatusErrorBucketNotEmpty will result.
*
* @param protocol gives the protocol to use for this request
* @param uriStyle gives the URI style to use for this request
* @param accessKeyId gives the Amazon Access Key ID for which to list owned
* buckets
* @param secretAccessKey gives the Amazon Secret Access Key for which to list
* owned buckets
* @param hostName is the S3 host name to use; if NULL is passed in, the
* default S3 host as provided to S3_initialize() will be used.
* @param bucketName is the name of the bucket to be deleted
* @param requestContext if non-NULL, gives the S3RequestContext to add this
* request to, and does not perform the request immediately. If NULL,
* performs the request immediately and synchronously.
* @param handler gives the callbacks to call as the request is processed and
* completed
* @param callbackData will be passed in as the callbackData parameter to
* all callbacks for this request
**/
void S3_delete_bucket(S3Protocol protocol, S3UriStyle uriStyle,
const char *accessKeyId, const char *secretAccessKey,
const char *hostName, const char *bucketName,
S3RequestContext *requestContext,
const S3ResponseHandler *handler, void *callbackData);
/**
* Lists keys within a bucket.
*
* @param bucketContext gives the bucket and associated parameters for this
* request
* @param prefix if present, gives a prefix for matching keys
* @param marker if present, only keys occuring after this value will be
* listed
* @param delimiter if present, causes keys that contain the same string
* between the prefix and the first occurrence of the delimiter to be
* rolled up into a single result element
* @param maxkeys is the maximum number of keys to return
* @param requestContext if non-NULL, gives the S3RequestContext to add this
* request to, and does not perform the request immediately. If NULL,
* performs the request immediately and synchronously.
* @param handler gives the callbacks to call as the request is processed and
* completed
* @param callbackData will be passed in as the callbackData parameter to
* all callbacks for this request
**/
void S3_list_bucket(const S3BucketContext *bucketContext,
const char *prefix, const char *marker,
const char *delimiter, int maxkeys,
S3RequestContext *requestContext,
const S3ListBucketHandler *handler, void *callbackData);
/** **************************************************************************
* Object Functions
************************************************************************** **/
/**
* Puts object data to S3. This overwrites any existing object at that key;
* note that S3 currently only supports full-object upload. The data to
* upload will be acquired by calling the handler's putObjectDataCallback.
*
* @param bucketContext gives the bucket and associated parameters for this
* request
* @param key is the key of the object to put to
* @param contentLength is required and gives the total number of bytes that
* will be put
* @param putProperties optionally provides additional properties to apply to
* the object that is being put to
* @param requestContext if non-NULL, gives the S3RequestContext to add this
* request to, and does not perform the request immediately. If NULL,
* performs the request immediately and synchronously.
* @param handler gives the callbacks to call as the request is processed and
* completed
* @param callbackData will be passed in as the callbackData parameter to
* all callbacks for this request
**/
void S3_put_object(const S3BucketContext *bucketContext, const char *key,
uint64_t contentLength,
const S3PutProperties *putProperties,
S3RequestContext *requestContext,
const S3PutObjectHandler *handler, void *callbackData);
/**
* Copies an object from one location to another. The object may be copied
* back to itself, which is useful for replacing metadata without changing
* the object.
*
* @param bucketContext gives the source bucket and associated parameters for
* this request
* @param key is the source key
* @param destinationBucket gives the destination bucket into which to copy
* the object. If NULL, the source bucket will be used.
* @param destinationKey gives the destination key into which to copy the
* object. If NULL, the source key will be used.
* @param putProperties optionally provides properties to apply to the object
* that is being put to. If not supplied (i.e. NULL is passed in),
* then the copied object will retain the metadata of the copied
* object.
* @param lastModifiedReturn returns the last modified date of the copied
* object
* @param eTagReturnSize specifies the number of bytes provided in the
* eTagReturn buffer
* @param eTagReturn is a buffer into which the resulting eTag of the copied
* object will be written
* @param handler gives the callbacks to call as the request is processed and
* completed
* @param callbackData will be passed in as the callbackData parameter to
* all callbacks for this request
* @param requestContext if non-NULL, gives the S3RequestContext to add this
* request to, and does not perform the request immediately. If NULL,
* performs the request immediately and synchronously.
* @param handler gives the callbacks to call as the request is processed and
* completed
* @param callbackData will be passed in as the callbackData parameter to
* all callbacks for this request
**/
void S3_copy_object(const S3BucketContext *bucketContext,
const char *key, const char *destinationBucket,
const char *destinationKey,
const S3PutProperties *putProperties,
int64_t *lastModifiedReturn, int eTagReturnSize,
char *eTagReturn, S3RequestContext *requestContext,
const S3ResponseHandler *handler, void *callbackData);
/**
* Gets an object from S3. The contents of the object are returned in the
* handler's getObjectDataCallback.
*
* @param bucketContext gives the bucket and associated parameters for this
* request
* @param key is the key of the object to get
* @param getConditions if non-NULL, gives a set of conditions which must be
* met in order for the request to succeed
* @param startByte gives the start byte for the byte range of the contents
* to be returned
* @param byteCount gives the number of bytes to return; a value of 0
* indicates that the contents up to the end should be returned
* @param requestContext if non-NULL, gives the S3RequestContext to add this
* request to, and does not perform the request immediately. If NULL,
* performs the request immediately and synchronously.
* @param handler gives the callbacks to call as the request is processed and
* completed
* @param callbackData will be passed in as the callbackData parameter to
* all callbacks for this request
**/
void S3_get_object(const S3BucketContext *bucketContext, const char *key,
const S3GetConditions *getConditions,
uint64_t startByte, uint64_t byteCount,
S3RequestContext *requestContext,
const S3GetObjectHandler *handler, void *callbackData);
/**
* Gets the response properties for the object, but not the object contents.
*
* @param bucketContext gives the bucket and associated parameters for this
* request
* @param key is the key of the object to get the properties of
* @param requestContext if non-NULL, gives the S3RequestContext to add this
* request to, and does not perform the request immediately. If NULL,
* performs the request immediately and synchronously.
* @param handler gives the callbacks to call as the request is processed and
* completed
* @param callbackData will be passed in as the callbackData parameter to
* all callbacks for this request
**/
void S3_head_object(const S3BucketContext *bucketContext, const char *key,
S3RequestContext *requestContext,
const S3ResponseHandler *handler, void *callbackData);
/**
* Deletes an object from S3.
*
* @param bucketContext gives the bucket and associated parameters for this
* request
* @param key is the key of the object to delete
* @param requestContext if non-NULL, gives the S3RequestContext to add this
* request to, and does not perform the request immediately. If NULL,
* performs the request immediately and synchronously.
* @param handler gives the callbacks to call as the request is processed and
* completed
* @param callbackData will be passed in as the callbackData parameter to
* all callbacks for this request
**/
void S3_delete_object(const S3BucketContext *bucketContext, const char *key,
S3RequestContext *requestContext,
const S3ResponseHandler *handler, void *callbackData);
/** **************************************************************************
* Access Control List Functions
************************************************************************** **/
/**
* Gets the ACL for the given bucket or object.
*
* @param bucketContext gives the bucket and associated parameters for this
* request
* @param key is the key of the object to get the ACL of; or NULL to get the
* ACL of the bucket
* @param ownerId must be supplied as a buffer of at least
* S3_MAX_GRANTEE_USER_ID_SIZE bytes, and will be filled in with the
* owner ID of the object/bucket
* @param ownerDisplayName must be supplied as a buffer of at least
* S3_MAX_GRANTEE_DISPLAY_NAME_SIZE bytes, and will be filled in with
* the display name of the object/bucket
* @param aclGrantCountReturn returns the number of S3AclGrant structures
* returned in the aclGrants parameter
* @param aclGrants must be passed in as an array of at least
* S3_MAX_ACL_GRANT_COUNT S3AclGrant structures, which will be filled
* in with the grant information for the ACL
* @param requestContext if non-NULL, gives the S3RequestContext to add this
* request to, and does not perform the request immediately. If NULL,
* performs the request immediately and synchronously.
* @param handler gives the callbacks to call as the request is processed and
* completed
* @param callbackData will be passed in as the callbackData parameter to
* all callbacks for this request
**/
void S3_get_acl(const S3BucketContext *bucketContext, const char *key,
char *ownerId, char *ownerDisplayName,
int *aclGrantCountReturn, S3AclGrant *aclGrants,
S3RequestContext *requestContext,
const S3ResponseHandler *handler, void *callbackData);
/**
* Sets the ACL for the given bucket or object.
*
* @param bucketContext gives the bucket and associated parameters for this
* request
* @param key is the key of the object to set the ACL for; or NULL to set the
* ACL for the bucket
* @param ownerId is the owner ID of the object/bucket. Unfortunately, S3
* requires this to be valid and thus it must have been fetched by a
* previous S3 request, such as a list_buckets request.
* @param ownerDisplayName is the owner display name of the object/bucket.
* Unfortunately, S3 requires this to be valid and thus it must have
* been fetched by a previous S3 request, such as a list_buckets
* request.
* @param aclGrantCount is the number of ACL grants to set for the
* object/bucket
* @param aclGrants are the ACL grants to set for the object/bucket
* @param requestContext if non-NULL, gives the S3RequestContext to add this
* request to, and does not perform the request immediately. If NULL,
* performs the request immediately and synchronously.
* @param handler gives the callbacks to call as the request is processed and
* completed
* @param callbackData will be passed in as the callbackData parameter to
* all callbacks for this request
**/
void S3_set_acl(const S3BucketContext *bucketContext, const char *key,
const char *ownerId, const char *ownerDisplayName,
int aclGrantCount, const S3AclGrant *aclGrants,
S3RequestContext *requestContext,
const S3ResponseHandler *handler, void *callbackData);
/** **************************************************************************
* Server Access Log Functions
************************************************************************** **/
/**
* Gets the service access logging settings for a bucket. The service access
* logging settings specify whether or not the S3 service will write service
* access logs for requests made for the given bucket, and if so, several
* settings controlling how these logs will be written.
*
* @param bucketContext gives the bucket and associated parameters for this
* request; this is the bucket for which service access logging is
* being requested
* @param targetBucketReturn must be passed in as a buffer of at least
* (S3_MAX_BUCKET_NAME_SIZE + 1) bytes in length, and will be filled
* in with the target bucket name for access logging for the given
* bucket, which is the bucket into which access logs for the specified
* bucket will be written. This is returned as an empty string if
* service access logging is not enabled for the given bucket.
* @param targetPrefixReturn must be passed in as a buffer of at least
* (S3_MAX_KEY_SIZE + 1) bytes in length, and will be filled in
* with the key prefix for server access logs for the given bucket,
* or the empty string if no such prefix is specified.
* @param aclGrantCountReturn returns the number of ACL grants that are
* associated with the server access logging for the given bucket.
* @param aclGrants must be passed in as an array of at least
* S3_MAX_ACL_GRANT_COUNT S3AclGrant structures, and these will be
* filled in with the target grants associated with the server access
* logging for the given bucket, whose number is returned in the
* aclGrantCountReturn parameter. These grants will be applied to the
* ACL of any server access logging log files generated by the S3
* service for the given bucket.
* @param requestContext if non-NULL, gives the S3RequestContext to add this
* request to, and does not perform the request immediately. If NULL,
* performs the request immediately and synchronously.
* @param handler gives the callbacks to call as the request is processed and
* completed
* @param callbackData will be passed in as the callbackData parameter to
* all callbacks for this request
**/
void S3_get_server_access_logging(const S3BucketContext *bucketContext,
char *targetBucketReturn,
char *targetPrefixReturn,
int *aclGrantCountReturn,
S3AclGrant *aclGrants,
S3RequestContext *requestContext,
const S3ResponseHandler *handler,
void *callbackData);
/**
* Sets the service access logging settings for a bucket. The service access
* logging settings specify whether or not the S3 service will write service
* access logs for requests made for the given bucket, and if so, several
* settings controlling how these logs will be written.
*
* @param bucketContext gives the bucket and associated parameters for this
* request; this is the bucket for which service access logging is
* being set
* @param targetBucket gives the target bucket name for access logging for the
* given bucket, which is the bucket into which access logs for the
* specified bucket will be written.
* @param targetPrefix is an option parameter which specifies the key prefix
* for server access logs for the given bucket, or NULL if no such
* prefix is to be used.
* @param aclGrantCount specifies the number of ACL grants that are to be
* associated with the server access logging for the given bucket.
* @param aclGrants is as an array of S3AclGrant structures, whose number is
* given by the aclGrantCount parameter. These grants will be applied
* to the ACL of any server access logging log files generated by the
* S3 service for the given bucket.
* @param requestContext if non-NULL, gives the S3RequestContext to add this
* request to, and does not perform the request immediately. If NULL,
* performs the request immediately and synchronously.
* @param handler gives the callbacks to call as the request is processed and
* completed
* @param callbackData will be passed in as the callbackData parameter to
* all callbacks for this request
**/
void S3_set_server_access_logging(const S3BucketContext *bucketContext,
const char *targetBucket,
const char *targetPrefix, int aclGrantCount,
const S3AclGrant *aclGrants,
S3RequestContext *requestContext,
const S3ResponseHandler *handler,
void *callbackData);
#ifdef __cplusplus
}
#endif
#endif /* LIBS3_H */
|