doc/index.html

   1 <html>
   2   <head>
   3     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   4     <link rel='stylesheet' type='text/css' href='style.css'>
   5     <title>ZS3 - Amazon S3 and CloudFront from Common Lisp</title>
   6     </head>
   7   <body>
   8
   9 <div id='content'>
  10  <h2>ZS3 - Amazon S3 and CloudFront from Common Lisp</h2>
  11
  12  <p>ZS3 is a Common Lisp library for working with
  13    Amazon's <a href="http://aws.amazon.com/s3/">Simple Storage
  14    Service</a> (S3)
  15    and <a href="http://aws.amazon.com/cloudfront/">CloudFront content
  16    delivery service</a>. It is available under a BSD-style license;
  17    see <a href='LICENSE'>LICENSE</a> for details.
  18
  19 The latest version is 1.1.5, released on June 11, 2011.
  20
  21  <p>Download shortcut: <a href='http://www.xach.com/lisp/zs3.tgz'>http://www.xach.com/lisp/zs3.tgz</a>
  22
  23  <h2>Contents</h2>
  24
  25  <ul>
  26    <li> <a href='#installation'>Installation</a>
  27    <li> <a href='#overview'>Overview</a>
  28    <li> <a href='#example'>Example Use</a>
  29    <li> <a href='#limitations'>Limitations</a>
  30    <li> <a href='#dictionary'>The ZS3 Dictionary</a>
  31      <ul>
  32        <li> <a href='#credentials'>Credentials</a>
  33        <li> <a href='#bucket-ops'>Operations on Buckets</a>
  34        <li> <a href='#querying-buckets'>Querying Buckets</a>
  35        <li> <a href='#object-ops'>Operations on Objects</a>
  36        <li> <a href='#access-control'>Access Control</a>
  37        <li> <a href='#access-logging'>Access Logging</a>
  38        <li> <a href='#misc'>Miscellaneous Operations</a>
  39        <li> <a href='#utility'>Utility Functions</a>
  40        <li> <a href='#cloudfront'>CloudFront</a>
  41      </ul>
  42    <li> <a href='#references'>References</a>
  43    <li> <a href='#acknowledgements'>Acknowledgements</a>
  44    <li> <a href='#feedback'>Feedback</a>
  45  </ul>
  46
  47  <a name='installation'><h2>Installation</h2></a>
  48
  49  <p>ZS3 depends on the following libraries:
  50
  51    <ul>
  52      <li> <a href="http://common-lisp.net/project/cxml/">Closure XML</a>
  53      <li> <a href="http://weitz.de/drakma/">Drakma</a> <b>1.0.0 or newer</b>
  54      <li> <a href="http://method-combination.net/lisp/ironclad/">Ironclad</a>
  55      <li> <a href="http://files.b9.com/cl-base64/">cl-base64</a>
  56      <li> <a href="http://puri.b9.com/">Puri</a>
  57    </ul>
  58
  59  <p>The easiest way to install ZS3 and all its required libraries is
  60  with <A href="http://www.quicklisp.org/">Quicklisp</a>. After
  61  Quicklisp is installed, the following will fetch and load ZS3:
  62
  63 <pre>
  64     (ql:quickload "zs3")
  65 </pre>
  66
  67  <p>For more information about incorporating ASDF-using libraries like
  68    ZS3 into your own projects,
  69    see <a href="http://xach.livejournal.com/278047.html">this short
  70    tutorial</a>.
  71
  72
  73 <a name='overview'><h2>Overview</h2></a>
  74
  75  <p>ZS3 provides an interface to two separate, but related, Amazon
  76  services: <a href="http://aws.amazon.com/s3/">S3</a>
  77  and <a href="http://aws.amazon.com/cloudfront/">CloudFront</a>
  78
  79  <p>Using Amazon S3 involves working with two kinds of resources:
  80  buckets and objects.
  81
  82  <p>Buckets are containers, and are used to organize and manage
  83    objects. Buckets are identified by their name, which must be unique
  84    across all of S3. A user may have up to 100 buckets in S3.
  85
  86  <p>Objects are stored within buckets. Objects consist of arbitrary
  87    binary data, from 1 byte to 5 gigabytes. They are identified by a
  88    key, which must be unique within a bucket. Objects can also have
  89    associated S3-specific metadata and HTTP metadata.
  90
  91  <p>For full documentation of the Amazon S3 system, see
  92    the <a href="http://developer.amazonwebservices.com/connect/entry.jspa?externalID=123&categoryID=48">Amazon
  93    S3 Technical Documentation</a>. ZS3 uses the REST
  94    interface for all its operations.
  95
  96  <p>Using Amazon CloudFront involves working with
  97    distributions. Distributions are objects that associate an S3
  98    bucket with primary cloudfront.net hostname and zero or more
  99    arbitrary CNAMEs. S3 objects requested through a CloudFront
 100    distribution are distributed to and cached in multiple locations
 101    throughout the world, reducing latency and improving throughput,
 102    compared to direct S3 requests.
 103
 104  <p>For full documentation of the Amazon CloudFront system, see the
 105    <a href="http://developer.amazonwebservices.com/connect/entry.jspa?externalID=1876&categoryID=213">Amazon
 106    CloudFront Technical Documentation</a>.
 107
 108  <p>For help with using ZS3, please see
 109  the <a href="http://groups.google.com/group/zs3-devel">zs3-devel</a>
 110  mailing list.
 111
 112 <a name='example'><h2>Example Use</h2></a>
 113
 114 <p>
 115 <pre class='code'>
 116   * <b>(asdf:oos 'asdf:load-op '#:zs3)</b>
 117   => <i>lots of stuff</i>
 118
 119   * <b>(defpackage #:demo (:use #:cl #:zs3))</b>
 120   => #&lt;PACKAGE "DEMO"&gt;
 121
 122   * <b>(in-package #:demo)</b>
 123   => #&lt;PACKAGE "DEMO"&gt;
 124
 125   * <b>(setf <a href='#*credentials*'>*credentials*</a> (<a href='#file-credentials'>file-credentials</a> "~/.aws"))</b>
 126   => #&lt;FILE-CREDENTIALS {100482AF91}>
 127
 128   * <b>(<a href='#bucket-exists-p'>bucket-exists-p</a> "zs3-demo")</b>
 129   => NIL
 130
 131   * <b>(<a href='#create-bucket'>create-bucket</a> "zs3-demo")</b>
 132   => #&lt;RESPONSE 200 "OK" {10040D3281}>
 133
 134   * <b>(<a href='#put-vector'>put-vector</a> (<a href='#octet-vector'>octet-vector</a> 8 6 7 5 3 0 9 ) "zs3-demo" "jenny")</b>
 135   => #&lt;RESPONSE 200 "OK" {10033EC2E1}>
 136
 137   * <b>(create-bucket "zs3 demo")</b>
 138   Error:
 139    InvalidBucketName: The specified bucket is not valid.
 140    For more information, see:
 141      <a href="http://docs.amazonwebservices.com/AmazonS3/2006-03-01/BucketRestrictions.html">http://docs.amazonwebservices.com/AmazonS3/2006-03-01/BucketRestrictions.html</a>
 142   [Condition of type INVALID-BUCKET-NAME]
 143
 144   * <b>(<a href='#copy-object'>copy-object</a> :from-bucket "zs3-demo" :from-key "jenny" :to-key "j2")</b>
 145   => #&lt;RESPONSE 200 "OK" {10040E3EA1}>
 146
 147   * <b>(<a href='#get-vector'>get-vector</a> "zs3-demo" "j2")</b>
 148   => #(8 6 7 5 3 0 9),
 149      ((:X-AMZ-ID-2 . "Huwo...")
 150       (:X-AMZ-REQUEST-ID . "304...")
 151       (:DATE . "Sat, 27 Sep 2008 15:01:03 GMT")
 152       (:LAST-MODIFIED . "Sat, 27 Sep 2008 14:57:31 GMT")
 153       (:ETAG . "\"f9e71fe2c41a10c0a78218e98a025520\"")
 154       (:CONTENT-TYPE . "binary/octet-stream")
 155       (:CONTENT-LENGTH . "7")
 156       (:CONNECTION . "close")
 157       (:SERVER . "AmazonS3"))
 158
 159   * <b>(<a href='#put-string'>put-string</a> "N&auml;men" "zs3-demo" "bork")</b>
 160   => #&lt;RESPONSE 200 "OK" {10047A3791}>
 161
 162   * <b>(values (get-vector "zs3-demo" "bork"))</b>
 163   => #(78 195 164 109 101 110)
 164
 165   * <b>(values (<a href='#get-file'>get-file</a> "zs3-demo" "bork" "bork.txt"))</b>
 166   => #P"bork.txt"
 167
 168   * <b>(setf *distribution* (<a href='#create-distribution'>create-distribution</a> "zs3-demo" :cnames "cdn.wigflip.com")</b>
 169   => #&lt;DISTRIBUTION X2S94L4KLZK5G0 for "zs3-demo.s3.amazonaws.com" [InProgress]>
 170
 171   * <b>(progn (sleep 180) (<a href='#refresh'>refresh</a> *distribution*))</b>
 172   => #&lt;DISTRIBUTION X2S94L4KLZK5G0 for "zs3-demo.s3.amazonaws.com" [Deployed]>
 173
 174   * <b>(<a href='#domain-name'>domain-name</a> *distribution*)</b>
 175   => "x214g1hzpjm1zp.cloudfront.net"
 176
 177   * <b>(<a href='#cnames'>cnames</a> *distribution*)</b>
 178   => ("cdn.wigflip.com")
 179
 180   * <b>(put-string "Hello, world" "zs3-demo" "cloudfront" :public t)</b>
 181   #&lt;RESPONSE 200 "OK" {10042689F1}>
 182
 183   * <b>(drakma:http-request "http://x214g1hzpjm1zp.cloudfront.net/cloudfront")</b>
 184   "Hello, world"
 185   200
 186   ((:X-AMZ-ID-2 . "NMc3IY3NzHGGEvV/KlzPgZMyDfPVT+ITtHo47Alqg00MboTxSX2f5XJzVTErfuHr")
 187    (:X-AMZ-REQUEST-ID . "52B050DC18638A00")
 188    (:DATE . "Thu, 05 Mar 2009 16:24:25 GMT")
 189    (:LAST-MODIFIED . "Thu, 05 Mar 2009 16:24:10 GMT")
 190    (:ETAG . "\"bc6e6f16b8a077ef5fbc8d59d0b931b9\"")
 191    (:CONTENT-TYPE . "text/plain")
 192    (:CONTENT-LENGTH . "12")
 193    (:SERVER . "AmazonS3")
 194    (:X-CACHE . "Miss from cloudfront")
 195    (:VIA . "1.0 ad78cb56da368c171e069e4444b2cbf6.cloudfront.net:11180")
 196    (:CONNECTION . "close"))
 197   #&lt;PURI:URI http://x214g1hzpjm1zp.cloudfront.net/cloudfront>
 198   #&lt;FLEXI-STREAMS:FLEXI-IO-STREAM {1002CE0781}>
 199   T
 200   "OK"
 201
 202   * <b>(drakma:http-request "http://x214g1hzpjm1zp.cloudfront.net/cloudfront")</b>
 203   "Hello, world"
 204   200
 205   ((:X-AMZ-ID-2 . "NMc3IY3NzHGGEvV/KlzPgZMyDfPVT+ITtHo47Alqg00MboTxSX2f5XJzVTErfuHr")
 206    (:X-AMZ-REQUEST-ID . "52B050DC18638A00")
 207    (:DATE . "Thu, 05 Mar 2009 16:24:25 GMT")
 208    (:LAST-MODIFIED . "Thu, 05 Mar 2009 16:24:10 GMT")
 209    (:ETAG . "\"bc6e6f16b8a077ef5fbc8d59d0b931b9\"")
 210    (:CONTENT-TYPE . "text/plain")
 211    (:CONTENT-LENGTH . "12")
 212    (:SERVER . "AmazonS3")
 213    (:AGE . "311")
 214    (:X-CACHE . "Hit from cloudfront")
 215    (:VIA . "1.0 0d78cb56da368c171e069e4444b2cbf6.cloudfront.net:11180")
 216    (:CONNECTION . "close"))
 217   #&lt;PURI:URI http://x214g1hzpjm1zp.cloudfront.net/cloudfront>
 218   #&lt;FLEXI-STREAMS:FLEXI-IO-STREAM {100360A781}>
 219   T
 220   "OK"
 221
 222 </pre>
 223
 224
 225 <a name='limitations'><h2>Limitations</h2></a>
 226
 227 <p>ZS3 supports almost all of the features of Amazon's S3 REST
 228 interface. Some features are unsupported or incompletely supported:
 229
 230   <ul>
 231     <li> No direct support
 232     for <a href="http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingDevPay.html">Amazon
 233     DevPay</a>
 234
 235     <li> No support for checking the 100-Continue response to avoid
 236     unnecessary large requests; this will hopefully be fixed with a
 237     future <a href='http://weitz.de/drakma/'>Drakma</a> release
 238
 239     <li> If a character in a key is encoded with multiple bytes in
 240       UTF-8, a bad interaction
 241       between <a href="http://puri.b9.com/">PURI</a> and Amazon's web
 242       servers will trigger a validation error.
 243
 244   </ul>
 245
 246 <a name='dictionary'><h2>The ZS3 Dictionary</h2></a>
 247
 248 <p>The following sections document the symbols that are exported from
 249 ZS3.
 250
 251
 252  <a name='credentials'><h3>Credentials</h3></a>
 253
 254 <p>
 255
 256 <div class='item'>
 257   <div class='type'><a name='*credentials*'>[Special variable]</a></div>
 258   <div class='signature'>
 259     <code class='name'>*credentials*</code>
 260   </div>
 261
 262   <blockquote class='description'>
 263     <p><code>*CREDENTIALS*</code> is the source of the Amazon Access
 264     Key and Secret Key for authenticated requests. Any object that has
 265     methods for the <a href='#access-key'><tt>ACCESS-KEY</tt></a>
 266     and <a href='#secret-key'><tt>SECRET-KEY</tt></a> generic
 267     functions may be used.
 268
 269     <p>If <code>*CREDENTIALS*</code> is a cons, it is treated as a
 270       list, and the first element of the list is taken as the access
 271       key and the second element of the list is taken as the secret
 272       key.
 273
 274     <p>The default value of <code>*CREDENTIALS*</code> is NIL, which
 275       will signal an error. You must set <code>*CREDENTIALS*</code> to
 276       something that follows the credentials generic function protocol
 277       to use ZS3.
 278
 279     <p>All ZS3 functions that involve authenticated requests take an
 280     optional <code class='kw'>:CREDENTIALS</code> keyword
 281     parameter. This parameter is bound to <code>*CREDENTIALS*</code>
 282     for the duration of the function call.
 283
 284     <p>The following illustrates how to implement a credentials object
 285       that gets the access and secret key from external environment
 286       variables.
 287
 288 <pre class='code'>
 289   (defclass environment-credentials () ())
 290
 291   (defmethod access-key ((credentials environment-credentials))
 292     (declare (ignore credentials))
 293     (getenv "AWS_ACCESS_KEY"))
 294
 295   (defmethod secret-key ((credentials environment-credentials))
 296     (declare (ignore credentials))
 297     (getenv "AWS_SECRET_KEY"))
 298
 299   (setf *credentials* (make-instance 'environment-credentials))
 300 </pre>
 301   </blockquote>
 302 </div>
 303
 304
 305 <div class='item'>
 306   <div class='type'><a name='access-key'>[Generic function]</a></div>
 307   <div class='signature'>
 308     <code class='name'>access-key</code>
 309     <span class='args'>
 310       <var>credentials</var>
 311     </span>
 312     <span class='result'>=> <var>access-key-string</var></span>
 313   </div>
 314
 315   <blockquote class='description'>
 316     <p>Returns the access key for <var>credentials</var>.
 317   </blockquote>
 318 </div>
 319
 320
 321 <div class='item'>
 322   <div class='type'><a name='secret-key'>[Generic function]</a></div>
 323   <div class='signature'>
 324     <code class='name'>secret-key</code>
 325     <span class='args'>
 326       <var>credentials</var>
 327     </span>
 328     <span class='result'>=> <var>secret-key-string</var></span>
 329   </div>
 330
 331   <blockquote class='description'>
 332     <p>Returns the secret key for <var>credentials</var>.
 333   </blockquote>
 334 </div>
 335
 336 <div class='item'>
 337   <div class='type'><a name='file-credentials'>[Function]</a></div>
 338   <div class='signature'>
 339     <code class='name'>file-credentials</code>
 340     <span class='args'>
 341       <var>pathname</var>
 342     </span>
 343     <span class='result'>=> <var>credentials</var></span>
 344   </div>
 345
 346   <blockquote class='description'>
 347     <p>Loads credentials on demand from <var>pathname</var>. The file
 348       named by <var>pathname</var> should be a text file with the
 349       access key on the first line and the secret key on the second
 350       line.
 351
 352     <p>It can be used like so:
 353
 354 <pre class='code'>
 355   (setf *credentials* (file-credentials "/etc/s3.conf"))
 356 </pre>
 357   </blockquote>
 358 </div>
 359
 360
 361
 362  <a name='bucket-ops'><h3>Operations on Buckets</h3></a>
 363
 364  <p>With ZS3, you can put, get, copy, and delete buckets. You can also
 365  get information about the bucket.
 366
 367 <div class='item'>
 368   <div class='type'><a name='all-buckets'>[Function]</a></div>
 369   <div class='signature'>
 370     <code class='name'>all-buckets</code>
 371     <span class='args'>
 372       <code class='llkw'>&amp;key</code> <var>credentials</var>
 373     </span>
 374     <span class='result'>=> <var>bucket-vector</var></span>
 375   </div>
 376
 377   <blockquote class='description'>
 378     <p>Returns a vector of all bucket objects. Bucket object
 379     attributes are accessible via <a href='#name'><tt>NAME</tt></a>
 380     and <a href='#creation-date'><tt>CREATION-DATE</tt></a>.
 381   </blockquote>
 382 </div>
 383
 384 <div class='item'>
 385   <div class='type'><a name='creation-date'>[Function]</a></div>
 386   <div class='signature'>
 387     <code class='name'>creation-date</code>
 388     <span class='args'>
 389       <var>bucket-object</var>
 390     </span>
 391     <span class='result'>=> <var>creation-universal-time</var></span>
 392   </div>
 393
 394   <blockquote class='description'>
 395     <p>Returns the creation date of <var>bucket-object</var>, which
 396       must be a bucket object, as a universal time.
 397   </blockquote>
 398 </div>
 399
 400
 401 <div class='item'>
 402   <div class='type'><a name='name'>[Function]</a></div>
 403   <div class='signature'>
 404     <code class='name'>name</code>
 405     <span class='args'>
 406       <var>object</var>
 407     </span>
 408     <span class='result'>=> <var>name-string</var></span>
 409   </div>
 410
 411   <blockquote class='description'>
 412     <p>Returns the string name of <var>object</var>, which must be a
 413       key object or bucket object.
 414   </blockquote>
 415 </div>
 416
 417
 418 <div class='item'>
 419   <div class='type'><a name='all-keys'>[Function]</a></div>
 420   <div class='signature'>
 421     <code class='name'>all-keys</code>
 422     <span class='args'>
 423       <var>bucket</var>
 424       <code class='llkw'>&amp;key</code>
 425       <var>prefix</var>
 426       <var>credentials</var>
 427     </span>
 428     <span class='result'>=> <var>key-vector</var></span>
 429   </div>
 430
 431   <blockquote class='description'>
 432     <p>Returns a vector of all key objects in <var>bucket</var> with names
 433     that start with the string <var>prefix</var>. If no prefix is
 434     specified, returns all keys. Keys in the vector are in
 435     alphabetical order by name. Key
 436     object attributes are accessible via
 437       <a href='#name'><tt>NAME</tt></a>,
 438       <a href='#size'><tt>SIZE</tt></a>,
 439       <a href='#etag'><tt>ETAG</tt></a>,
 440       <a href='#last-modified'><tt>LAST-MODIFIED</tt></a>,
 441       and <a href='#owner'><tt>OWNER</tt></a>.
 442
 443     <p>This function is built
 444       on <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> and may
 445       involve multiple requests if a bucket has more than 1000 keys.
 446   </blockquote>
 447 </div>
 448
 449
 450 <div class='item'>
 451   <div class='type'><a name='bucket-exists-p'>[Function]</a></div>
 452   <div class='signature'>
 453     <code class='name'>bucket-exists-p</code>
 454     <span class='args'>
 455       <var>bucket</var>
 456       <code class='llkw'>&amp;key</code>
 457       <var>credentials</var>
 458     </span>
 459     <span class='result'>=> <var>boolean</var></span>
 460   </div>
 461
 462   <blockquote class='description'>
 463     <p>Returns <i>true</i> if <var>bucket</var> exists.
 464   </blockquote>
 465 </div>
 466
 467
 468 <div class='item'>
 469   <div class='type'><a name='create-bucket'>[Function]</a></div>
 470   <div class='signature'>
 471     <code class='name'>create-bucket</code>
 472     <span class='args'>
 473       <var>name</var>
 474       <code class='llkw'>&amp;key</code>
 475       <var>access-policy</var>
 476       <var>public</var>
 477       <var>location</var>
 478       <var>credentials</var>
 479     </span>
 480     <span class='result'>=> |</span>
 481   </div>
 482
 483   <blockquote class='description'>
 484     <p>Creates a bucket named <var>name</var>.
 485
 486     <p>If provided, <var>access-policy</var> should be one of the
 487     following:
 488
 489       <ul>
 490         <li> <code class='kw'>:PRIVATE</code> - bucket owner is
 491           granted <code class='kw'>:FULL-CONTROL</code>; this is the
 492           default behavior if no access policy is provided
 493         <li> <code class='kw'>:PUBLIC-READ</code> - all users,
 494           regardless of authentication, can query the bucket's contents
 495         <li> <code class='kw'>:PUBLIC-READ-WRITE</code> - all users,
 496           regardless of authentication, can query the bucket's
 497           contents and create new objects in the bucket
 498         <li> <code class='kw'>:AUTHENTICATED-READ</code> -
 499           authenticated Amazon AWS users can query the bucket
 500       </ul>
 501
 502     <p>For more information about access policies,
 503     see <a href='http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTAccessPolicy.html'>Canned
 504     Access Policies</a> in the Amazon S3 developer documentation.
 505
 506     <p>If <var>public</var> is <i>true</i>, it has the same effect as
 507       providing an <var>access-policy</var>
 508       of <code class='kw'>:PUBLIC-READ</code>. An error is signaled if
 509       both <var>public</var> and
 510       <var>access-policy</var> are provided.
 511
 512     <p>If <var>location</var> is "EU", the bucket will be created in
 513       Europe. See <a href="http://docs.amazonwebservices.com/AmazonS3/2006-03-01/BucketConfiguration.html">Bucket
 514       Configuration Options</a> in the Amazon S3 developer
 515       documentation for more information about location constraints.
 516   </blockquote>
 517 </div>
 518
 519
 520 <div class='item'>
 521   <div class='type'><a name='delete-bucket'>[Function]</a></div>
 522   <div class='signature'>
 523     <code class='name'>delete-bucket</code>
 524     <span class='args'>
 525       <var>bucket</var> <code class='llkw'>&amp;key</code> <var>credentials</var>
 526     </span>
 527     <span class='result'>=> |</span>
 528   </div>
 529
 530   <blockquote class='description'>
 531     <p>Deletes <var>bucket</var>. Signals a BUCKET-NOT-EMPTY error if
 532 the bucket is not empty, or a NO-SUCH-BUCKET error if there is no
 533 bucket with the given name.
 534
 535   </blockquote>
 536 </div>
 537
 538
 539 <div class='item'>
 540   <div class='type'><a name='bucket-location'>[Function]</a></div>
 541   <div class='signature'>
 542     <code class='name'>bucket-location</code>
 543     <span class='args'>
 544       <var>bucket</var> <code class='llkw'>&amp;key</code> <var>credentials</var>
 545     </span>
 546     <span class='result'>=> <var>location</var></span>
 547   </div>
 548
 549   <blockquote class='description'>
 550     <p>Returns the location specified when creating a bucket, or NIL if no
 551       location was specified.
 552   </blockquote>
 553 </div>
 554
 555
 556 <a name='querying-buckets'><h3>Querying Buckets</h3></a>
 557
 558 <p>S3 has a flexible interface for querying a bucket for information
 559   about its contents. ZS3 supports this interface via
 560   <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a>,
 561    <a href='#continue-bucket-query'><tt>CONTINUE-BUCKET-QUERY</tt></a>,
 562    and related functions.
 563
 564 <div class='item'>
 565   <div class='type'><a name='query-bucket'>[Function]</a></div>
 566   <div class='signature'>
 567     <code class='name'>query-bucket</code>
 568     <span class='args'>
 569       <var>bucket</var>
 570       <code class='llkw'>&amp;key</code>
 571       <var>prefix</var>
 572       <var>marker</var>
 573       <var>max-keys</var>
 574       <var>delimiter</var>
 575       <var>credentials</var>
 576     </span>
 577     <span class='result'>=> <var>response</var></span>
 578   </div>
 579
 580   <blockquote class='description'>
 581     <p>Query <var>bucket</var> for key information. Returns a response
 582     object that has the result of the query. Response attributes are
 583     accessible via
 584       <a href='#bucket-name'><tt>BUCKET-NAME</tt></a>,
 585       <a href='#prefix'><tt>PREFIX</tt></a>,
 586       <a href='#marker'><tt>MARKER</tt></a>,
 587       <a href='#delimiter'><tt>DELIMITER</tt></a>,
 588       <a href='#truncatedp'><tt>TRUNCATEDP</tt></a>,
 589       <a href='#keys'><tt>KEYS</tt></a>, and
 590       <a href='#common-prefixes'><tt>COMMON-PREFIXES</tt></a>.
 591
 592     <p>Amazon might return fewer key objects than actually match the
 593       query parameters, based on <var>max-keys</var> or the result
 594       limit of 1000 key objects. In that
 595       case, <a href='#truncatedp'><tt>TRUNCATEDP</tt></a>
 596       for <var>response</var> is <i>true</i>, and
 597       <a href='#continue-bucket-query'><tt>CONTINUE-BUCKET-QUERY</tt></a>
 598       can be used with <var>response</var> be used to get successive
 599       responses for the query parameters.
 600
 601     <p>When <var>prefix</var> is supplied, only key objects with names
 602       that start with <var>prefix</var> will be returned
 603       in <var>response</var>.
 604
 605     <p>When <var>marker</var> is supplied, only key objects with names
 606       occurring lexically after <var>marker</var> will be returned in
 607       <var>response</var>.
 608
 609     <p>When <var>max-keys</var> is supplied, it places an inclusive
 610       upper limit on the number of key objects returned
 611       in <var>response</var>. Note that Amazon currently limits
 612       responses to at most 1000 key objects even
 613       if <var>max-keys</var> is greater than 1000.
 614
 615     <p>When <var>delimiter</var> is supplied, key objects that have
 616       the delimiter string after <var>prefix</var> in their names are
 617       not returned in the <a href='#keys'><tt>KEYS</tt></a> attribute
 618       of the response, but are instead accumulated into the
 619       <a href='#common-prefixes'><tt>COMMON-PREFIXES</tt></a>
 620       attribute of the response. For example:
 621 <pre class='code'>
 622   * <b>(all-keys "zs3-demo")</b>
 623   => #(#&lt;KEY "a" 4>
 624        #&lt;KEY "b/1" 4>
 625        #&lt;KEY "b/2" 4>
 626        #&lt;KEY "b/3" 4>
 627        #&lt;KEY "c/10" 4>
 628        #&lt;KEY "c/20" 4>
 629        #&lt;KEY "c/30" 4>)
 630
 631   * <b>(setf *response* (query-bucket "zs3-demo" :delimiter "/"))</b>
 632   => #&lt;BUCKET-LISTING "zs3-demo">
 633
 634   * <b>(values (keys *response*) (common-prefixes *response*))</b>
 635   => #(#&lt;KEY "a" 4>),
 636      #("b/"
 637        "c/")
 638
 639   * <b>(setf *response* (query-bucket "zs3-demo" :delimiter "/" :prefix "b/"))</b>
 640   => #&lt;BUCKET-LISTING "zs3-demo">
 641
 642   * <b>(values (keys *response*) (common-prefixes *response*))</b>
 643   => #(#&lt;KEY "b/1" 4>
 644        #&lt;KEY "b/2" 4>
 645        #&lt;KEY "b/3" 4>),
 646      #()</pre>
 647
 648     <p>For more information about bucket queries,
 649     see <a href="http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTBucketGET.html">GET
 650     Bucket</a> in the Amazon S3 developer documentation.
 651
 652   </blockquote>
 653
 654 </div>
 655
 656
 657 <div class='item'>
 658   <div class='type'><a name='continue-bucket-query'>[Function]</a></div>
 659   <div class='signature'>
 660     <code class='name'>continue-bucket-query</code>
 661     <span class='args'>
 662       <var>response</var>
 663     </span>
 664     <span class='result'>=> <var>response</var></span>
 665   </div>
 666
 667   <blockquote class='description'>
 668     <p>If <var>response</var> is a truncated response from a previous
 669     call to
 670       <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a>,
 671       continue-bucket-query returns the result of resuming the query at the
 672       truncation point. When there are no more results,
 673       continue-bucket-query returns NIL.
 674   </blockquote>
 675 </div>
 676
 677 <div class='item'>
 678   <div class='type'><a name='bucket-name'>[Function]</a></div>
 679   <div class='signature'>
 680     <code class='name'>bucket-name</code>
 681     <span class='args'>
 682       <var>response</var>
 683     </span>
 684     <span class='result'>=> <var>name</var></span>
 685   </div>
 686
 687   <blockquote class='description'>
 688     <p>Returns the name of the bucket used in the call
 689       to <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> that
 690       produced <var>response</var>.
 691   </blockquote>
 692 </div>
 693
 694
 695
 696
 697 <div class='item'>
 698   <div class='type'><a name='keys'>[Function]</a></div>
 699   <div class='signature'>
 700     <code class='name'>keys</code>
 701     <span class='args'>
 702       <var>response</var>
 703     </span>
 704     <span class='result'>=> <var>keys-vector</var></span>
 705   </div>
 706
 707   <blockquote class='description'>
 708     <p>Returns the vector of key objects in <var>response</var>. Key
 709     object attributes are accessible via
 710       <a href='#name'><tt>NAME</tt></a>,
 711       <a href='#size'><tt>SIZE</tt></a>,
 712       <a href='#etag'><tt>ETAG</tt></a>,
 713       <a href='#last-modified'><tt>LAST-MODIFIED</tt></a>,
 714       and <a href='#owner'><tt>OWNER</tt></a>.
 715   </blockquote>
 716 </div>
 717
 718
 719 <div class='item'>
 720   <div class='type'><a name='common-prefixes'>[Function]</a></div>
 721   <div class='signature'>
 722     <code class='name'>common-prefixes</code>
 723     <span class='args'>
 724       <var>response</var>
 725     </span>
 726     <span class='result'>=> <var>prefix-vector</var></span>
 727   </div>
 728
 729   <blockquote class='description'>
 730     <p>Returns a vector of common prefix strings, based on the
 731       delimiter argument of
 732       the <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> call that
 733       produced <var>response</var>.
 734   </blockquote>
 735 </div>
 736
 737
 738 <div class='item'>
 739   <div class='type'><a name='prefix'>[Function]</a></div>
 740   <div class='signature'>
 741     <code class='name'>prefix</code>
 742     <span class='args'>
 743       <var>response</var>
 744     </span>
 745     <span class='result'>=> <var>prefix-string</var></span>
 746   </div>
 747
 748   <blockquote class='description'>
 749     <p>Returns the prefix given to
 750     the <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> call that
 751     produced <var>response</var>. If present, all keys
 752     in <var>response</var> have <var>prefix-string</var> as a prefix.
 753   </blockquote>
 754 </div>
 755
 756 <div class='item'>
 757   <div class='type'><a name='marker'>[Function]</a></div>
 758   <div class='signature'>
 759     <code class='name'>marker</code>
 760     <span class='args'>
 761       <var>response</var>
 762     </span>
 763     <span class='result'>=> <var>marker</var></span>
 764   </div>
 765
 766   <blockquote class='description'>
 767     <p>Returns the marker given to
 768       the <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> call that
 769       produced <var>response</var>. If present,
 770       it lexically precedes all key names in the response.
 771   </blockquote>
 772 </div>
 773
 774 <div class='item'>
 775   <div class='type'><a name='delimiter'>[Function]</a></div>
 776   <div class='signature'>
 777     <code class='name'>delimiter</code>
 778     <span class='args'>
 779       <var>response</var>
 780     </span>
 781     <span class='result'>=> <var>delimiter</var></span>
 782   </div>
 783
 784   <blockquote class='description'>
 785     <p>Returns the delimiter used in
 786       the <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> call that
 787       produced <var>response</var>.
 788   </blockquote>
 789 </div>
 790
 791
 792 <div class='item'>
 793   <div class='type'><a name='truncatedp'>[Function]</a></div>
 794   <div class='signature'>
 795     <code class='name'>truncatedp</code>
 796     <span class='args'>
 797       <var>response</var>
 798     </span>
 799     <span class='result'>=> <var>boolean</var></span>
 800   </div>
 801
 802   <blockquote class='description'>
 803     <p>Returns <i>true</i> if <var>response</var> is truncated; that
 804     is, if there is more data to retrieve for a
 805     given <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a>
 806     query. <a href='#continue-bucket-query'><tt>CONTINUE-BUCKET-QUERY</tt></a>
 807     may be used to fetch more data.
 808   </blockquote>
 809 </div>
 810
 811
 812 <div class='item'>
 813   <div class='type'><a name='last-modified'>[Function]</a></div>
 814   <div class='signature'>
 815     <code class='name'>last-modified</code>
 816     <span class='args'>
 817       <var>key-object</var>
 818     </span>
 819     <span class='result'>=> <var>universal-time</var></span>
 820   </div>
 821
 822   <blockquote class='description'>
 823     <p>Returns a universal time representing the last modified time
 824     of <var>key-object</var>.
 825   </blockquote>
 826 </div>
 827
 828
 829 <div class='item'>
 830   <div class='type'><a name='etag'>[Function]</a></div>
 831   <div class='signature'>
 832     <code class='name'>etag</code>
 833     <span class='args'>
 834       <var>key-object</var>
 835     </span>
 836     <span class='result'>=> <var>etag-string</var></span>
 837   </div>
 838
 839   <blockquote class='description'>
 840     <p>Returns the etag for <var>key-object</var>.
 841   </blockquote>
 842 </div>
 843
 844
 845 <div class='item'>
 846   <div class='type'><a name='size'>[Function]</a></div>
 847   <div class='signature'>
 848     <code class='name'>size</code>
 849     <span class='args'>
 850       <var>key-object</var>
 851     </span>
 852     <span class='result'>=> <var>size</var></span>
 853   </div>
 854
 855   <blockquote class='description'>
 856     <p>Returns the size, in octets, of <var>key-object</var>.
 857   </blockquote>
 858 </div>
 859
 860
 861 <div class='item'>
 862   <div class='type'><a name='owner'>[Function]</a></div>
 863   <div class='signature'>
 864     <code class='name'>owner</code>
 865     <span class='args'>
 866       <var>key-object</var>
 867     </span>
 868     <span class='result'>=> <var>owner</var></span>
 869   </div>
 870
 871   <blockquote class='description'>
 872       <p>Returns the owner of <var>key-object</var>, or NIL if no owner
 873       information is available.
 874   </blockquote>
 875 </div>
 876
 877
 878
 879
 880 <a name='object-ops'><h3>Operations on Objects</h3></a>
 881
 882 <p>Objects are the stored binary data in S3. Every object is uniquely
 883   identified by a bucket/key pair. ZS3 has several functions for
 884   storing and fetching objects, and querying object attributes.
 885
 886 <div class='item'>
 887   <div class='type'><a name='get-object'>[Function]</a></div>
 888   <div class='signature'>
 889     <code class='name'>get-object</code>
 890     <span class='args'>
 891       <var>bucket</var>
 892       <var>key</var>
 893       <code class='llkw'>&amp;key</code>
 894       <var>output</var> <br>
 895       <var>start</var> <var>end</var> <br>
 896       <var>when-modified-since</var> <var>unless-modified-since</var> <br>
 897       <var>when-etag-matches</var> <var>unless-etag-matches</var> <br>
 898       <var>if-exists</var> <var>string-external-format</var>
 899       <var>credentials</var>
 900     </span>
 901     <span class='result'>=> <var>object</var></span>
 902   </div>
 903
 904   <blockquote class='description'>
 905     <p>Fetch the object referenced by <var>bucket</var>
 906     and <var>key</var>. The secondary value of all successful requests
 907     is an alist of <a href='http://weitz.de/drakma/'>Drakma</a>-style
 908     response HTTP headers.
 909
 910     <p>If <var>output</var> is <code class='kw'>:VECTOR</code> (the
 911     default), the object's octets are returned in a vector.
 912
 913     <p>If <var>output</var> is <code class='kw'>:STRING</code>, the
 914     object's octets are converted to a string using the encoding
 915     specified by <var>string-external-format</var>, which defaults
 916     to <code class='kw'>:UTF-8</code>. See <a href="http://weitz.de/flexi-streams/#external-formats">External
 917     formats</a> in the FLEXI-STREAMS documentation for supported
 918     values for the string external format. Note that, even
 919     when <var>output</var> is <code class='kw'>:STRING</code>, the
 920     start and end arguments operate on the object's underlying octets,
 921     not the string representation in a particular encoding. It's
 922     possible to produce a subsequence of the object's octets that are
 923     not valid in the desired encoding.
 924
 925     <p>If <var>output</var> is a string or pathname, the object's
 926     octets are saved to a file identified by the string or
 927     pathname. The <var>if-exists</var> argument is passed
 928     to <code>WITH-OPEN-FILE</code> to control the behavior when the
 929     output file already exists. It defaults
 930     to <code class='kw'>:SUPERSEDE</code>.
 931
 932     <p><var>start</var> marks the first index fetched from the
 933     object's data. <var>end</var> specifies the index after the last
 934     octet fetched. If start is NIL, it defaults to 0. If end is nil,
 935     it defaults to the total length of the object. If
 936     both <var>start</var> and <var>end</var> are
 937     provided, <var>start</var> must be less than or equal
 938     to <var>end</var>.
 939
 940     <p><var>when-modified-since</var>
 941     and <var>unless-modified-since</var> are optional. If
 942     <var>when-modified-since</var> is provided, the result will be the normal
 943     object value if the object has been modified since the provided
 944     universal time, NIL otherwise. The logic is reversed for
 945     <var>unless-modified-since</var>.
 946
 947     <p><var>when-etag-matches</var> and <var>unless-etag-matches</var> are optional. If
 948     <var>when-etag-matches</var> is provided, the result will be the
 949     normal object value if the object's etag matches the provided
 950     string, NIL otherwise. The logic is reversed
 951     for <var>unless-etag-matches</var>.
 952
 953   </blockquote>
 954 </div>
 955
 956 <div class='item'>
 957   <div class='type'><a name='get-vector'>[Function]</a></div>
 958   <div class='signature'>
 959     <code class='name'>get-vector</code>
 960     <span class='args'>
 961       <var>bucket</var> <var>key</var>
 962       <code class='llkw'>&amp;key</code>
 963       <var>start</var> <var>end</var>
 964       <var>when-modified-since</var> <var>unless-modified-since</var>
 965       <var>when-etag-matches</var> <var>unless-etag-matches</var>
 966       <var>credentials</var>
 967     </span>
 968     <span class='result'>=> <var>vector</var></span>
 969   </div>
 970
 971   <blockquote class='description'>
 972     <p>get-vector is a convenience interface to <a href='#get-object'><tt>GET-OBJECT</tt></a>. It is equivalent
 973       to calling:
 974
 975 <pre class='code'>
 976   (get-object bucket key <b>:output :vector</b> ...)
 977 </pre>
 978   </blockquote>
 979 </div>
 980
 981 <div class='item'>
 982   <div class='type'><a name='get-string'>[Function]</a></div>
 983   <div class='signature'>
 984     <code class='name'>get-string</code>
 985     <span class='args'>
 986       <var>bucket</var> <var>key</var>
 987       <code class='llkw'>&amp;key</code>
 988       <var>external-format</var>
 989       <var>start</var> <var>end</var>
 990       <var>when-modified-since</var>
 991       <var>unless-modified-since</var>
 992       <var>when-etag-matches</var>
 993       <var>unless-etag-matches</var>
 994       <var>credentials</var>
 995     </span>
 996     <span class='result'>=> <var>string</var></span>
 997   </div>
 998
 999   <blockquote class='description'>
1000     get-string is a convenience interface
1001     to <a href='#get-object'><tt>GET-OBJECT</tt></a>. It is equivalent
1002     to calling:
1003
1004 <pre class='code'>
1005   (get-object bucket key <b>:output :string</b> :string-external-format external-format ...)
1006 </pre>
1007
1008   </blockquote>
1009 </div>
1010
1011 <div class='item'>
1012   <div class='type'><a name='get-file'>[Function]</a></div>
1013   <div class='signature'>
1014     <code class='name'>get-file</code>
1015     <span class='args'>
1016       <var>bucket</var> <var>key</var> <var>file</var>
1017       <code class='llkw'>&amp;key</code>
1018       <var>start</var> <var>end</var>
1019       <var>when-modified-since</var>
1020       <var>unless-modified-since</var>
1021       <var>when-etag-matches</var>
1022       <var>unless-etag-matches</var>
1023       <var>credentials</var>
1024     </span>
1025     <span class='result'>=> <var>pathname</var></span>
1026   </div>
1027
1028   <blockquote class='description'>
1029     <p>get-file is a convenience interface
1030       to <a href='#get-object'><tt>GET-OBJECT</tt></a>. It is
1031       equivalent to calling:
1032
1033 <pre class='code'>
1034   (get-object bucket key <b>:output file</b> ...)
1035 </pre>
1036
1037   </blockquote>
1038 </div>
1039
1040
1041 <div class='item'>
1042   <div class='type'><a name='put-object'>[Function]</a></div>
1043   <div class='signature'>
1044     <code class='name'>put-object</code>
1045     <span class='args'>
1046       <var>object</var> <var>bucket</var> <var>key</var>
1047       <code class='llkw'>&amp;key</code>
1048       <var>access-policy</var>
1049       <var>public</var>
1050       <var>metadata</var>
1051       <var>string-external-format</var>
1052       <var>cache-control</var>
1053       <var>content-encoding</var>
1054       <var>content-disposition</var>
1055       <var>content-type</var>
1056       <var>expires</var>
1057       <var>credentials</var>
1058     </span>
1059     <span class='result'>=> |</span>
1060   </div>
1061
1062   <blockquote class='description'>
1063     <p>Stores the octets of <var>object</var> in the location
1064     identified by <var>bucket</var> and <var>key</var>.
1065
1066     <p>If <i>object</i> is an octet vector, it is stored directly.
1067
1068     <p>If <i>object</i> is a string, it is converted to an octet
1069     vector using <i>string-external-format</i>, which defaults
1070     to <code class='kw'>:UTF-8</code>, then
1071     stored. See <a href="http://weitz.de/flexi-streams/#external-formats">External
1072     formats</a> in the FLEXI-STREAMS documentation for supported
1073     values for the string external format.
1074
1075     <p>If <i>object</i> is a pathname, its contents are loaded in
1076     memory as an octet vector and stored.
1077
1078     <p>If provided, <var>access-policy</var> should be one of the
1079     following:
1080
1081       <ul>
1082         <li> <code class='kw'>:PRIVATE</code> - object owner is
1083           granted <code class='kw'>:FULL-CONTROL</code>; this is the
1084           default behavior if no access policy is provided
1085         <li> <code class='kw'>:PUBLIC-READ</code> - all users,
1086           regardless of authentication, can read the object
1087         <li> <code class='kw'>:AUTHENTICATED-READ</code> -
1088           authenticated Amazon AWS users can read the object
1089       </ul>
1090
1091     <p>For more information about access policies,
1092       see <a href='http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTAccessPolicy.html'>Canned
1093         Access Policies</a> in the Amazon S3 developer documentation.
1094
1095     <p>If <var>public</var> is <i>true</i>, it has the same effect as
1096       providing an <var>access-policy</var>
1097       of <code class='kw'>:PUBLIC-READ</code>. An error is signaled if
1098       both <var>public</var> and
1099       <var>access-policy</var> are provided.
1100
1101
1102     <p>If provided, <var>metadata</var> should be an alist of Amazon
1103     metadata to set on the object. When the object is fetched again,
1104     the metadata will be returned in HTTP headers prefixed with
1105     "x-amz-meta-".
1106
1107     <p>The <i>cache-control</i>, <i>content-encoding</i>, <i>content-disposition</i>,
1108     <i>content-type</i>, and <i>expires</i> values are all used to set
1109     HTTP properties of the object that are returned with subsequent
1110     GET or HEAD requests. If <i>content-type</i> is not set, it
1111     defaults to "binary/octet-stream". The others default to
1112     NIL. If <i>expires</i> is provided, it should be a universal time.
1113   </blockquote>
1114 </div>
1115
1116 <div class='item'>
1117   <div class='type'><a name='put-vector'>[Function]</a></div>
1118   <div class='signature'>
1119     <code class='name'>put-vector</code>
1120     <span class='args'>
1121       <var>vector</var>
1122       <var>bucket</var>
1123       <var>key</var> <code class='llkw'>&amp;key</code>
1124       <var>start</var> <var>end</var>
1125       <var>access-policy</var>
1126       <var>public</var> <var>metadata</var>
1127       <var>content-disposition</var>
1128       <var>content-encoding</var>
1129       <var>content-type</var>
1130       <var>expires</var>
1131       <var>credentials</var>
1132     </span>
1133     <span class='result'>=> |</span>
1134   </div>
1135
1136   <blockquote class='description'>
1137     <p>put-vector is a convenience interface
1138     to <a href='#put-object'><tt>PUT-OBJECT</tt></a>. It is similar
1139     to calling:
1140
1141 <pre class='code'>
1142   (put-object vector bucket key ...)
1143 </pre>
1144   </blockquote>
1145
1146   <p>If one of <var>start</var> or <var>end</var> is provided, they
1147     are used as bounding index designators on the string, and only a
1148     subsequence is used.
1149 </div>
1150
1151 <div class='item'>
1152   <div class='type'><a name='put-string'>[Function]</a></div>
1153   <div class='signature'>
1154     <code class='name'>put-string</code>
1155     <span class='args'>
1156       <var>string</var> <var>bucket</var> <var>key</var>
1157       <code class='llkw'>&amp;key</code>
1158       <var>start</var> <var>end</var>
1159       <var>external-format</var>
1160       <var>access-policy</var>
1161       <var>public</var> <var>metadata</var>
1162       <var>content-disposition</var>
1163       <var>content-encoding</var>
1164       <var>content-type</var>
1165       <var>expires</var>
1166       <var>credentials</var>
1167     </span>
1168     <span class='result'>=> |</span>
1169   </div>
1170
1171   <blockquote class='description'>
1172     <p>put-string is a convenience interface
1173 to <a href='#put-object'><tt>PUT-OBJECT</tt></a>. It is similar to
1174 calling:
1175
1176 <pre class='code'>
1177   (put-object string bucket key :string-external-format external-format ...)
1178 </pre>
1179   </blockquote>
1180
1181   <p>If one of <var>start</var> or end is <var>supplied</var>, they
1182     are used as bounding index designators on the string, and only a
1183     substring is used.
1184 </div>
1185
1186 <div class='item'>
1187   <div class='type'><a name='put-file'>[Function]</a></div>
1188   <div class='signature'>
1189     <code class='name'>put-file</code>
1190     <span class='args'>
1191       <var>file</var> <var>bucket</var> <var>key</var>
1192       <code class='llkw'>&amp;key</code>
1193       <var>start</var> <var>end</var>
1194       <var>access-policy</var>
1195       <var>public</var> <var>metadata</var>
1196       <var>content-disposition</var> <var>content-encoding</var> <var>content-type</var>
1197       <var>expires</var>
1198       <var>credentials</var>
1199     </span>
1200     <span class='result'>=> |</span>
1201   </div>
1202
1203   <blockquote class='description'>
1204     <p>put-file is a convenience interface
1205     to <a href='#put-object'><tt>PUT-OBJECT</tt></a>. It is almost
1206     equivalent to calling:
1207
1208 <pre class='code'>
1209   (put-object (pathname file) bucket key ...)
1210 </pre>
1211
1212     <p>If <var>key</var> is T, the <code>FILE-NAMESTRING</code> of
1213       the file is used as the key instead of <i>key</i>.
1214
1215     <p>If one of <var>start</var> or <var>end</var> is supplied, only
1216       a subset of the file is used. If <var>start</var> is not
1217       NIL, <var>start</var> octets starting from the beginning of the
1218       file are skipped. If <var>end</var> is not NIL, octets in the
1219       file at and after <var>end</var> are ignored. An error of type
1220       <tt>CL:END-OF-FILE</tt> is signaled if <var>end</var> is
1221       provided and the file size is less than <var>end</var>.
1222   </blockquote>
1223 </div>
1224
1225
1226 <div class='item'>
1227   <div class='type'><a name='put-stream'>[Function]</a></div>
1228   <div class='signature'>
1229     <code class='name'>put-stream</code>
1230     <span class='args'>
1231       <var>file</var> <var>bucket</var> <var>key</var>
1232       <code class='llkw'>&amp;key</code>
1233       <var>start</var> <var>end</var>
1234       <var>access-policy</var>
1235       <var>public</var> <var>metadata</var>
1236       <var>content-disposition</var> <var>content-encoding</var> <var>content-type</var>
1237       <var>expires</var>
1238       <var>credentials</var>
1239     </span>
1240     <span class='result'>=> |</span>
1241   </div>
1242
1243   <blockquote class='description'>
1244     <p>put-stream is similar to
1245     to <a href='#put-object'><tt>PUT-OBJECT</tt></a>. It has the same
1246     effect as collecting octets from <var>stream</var> into a vector
1247     and using:
1248
1249 <pre class='code'>
1250   (put-object vector bucket key ...)
1251 </pre>
1252
1253     <p>If <var>start</var> is not NIL, <var>start</var> octets
1254       starting from the current position in the stream are skipped
1255       before collecting.
1256
1257     <p>If <var>end</var> is NIL, octets are collected until the end of
1258       the stream is reached.
1259
1260     <p>If <var>end</var> is not NIL, collecting octets stops just
1261       before reaching <var>end</var> in the stream. An error of type
1262       <tt>CL:END-OF-FILE</tt> is signaled if the stream ends
1263       prematurely.
1264   </blockquote>
1265 </div>
1266
1267
1268 <div class='item'>
1269   <div class='type'><a name='copy-object'>[Function]</a></div>
1270   <div class='signature'>
1271     <code class='name'>copy-object</code>
1272     <span class='args'>
1273       <code class='llkw'>&amp;key</code>
1274       <var>from-bucket</var>
1275       <var>from-key</var>
1276       <var>to-bucket</var>
1277       <var>to-key</var> <br>
1278       <var>access-policy</var>
1279       <var>public</var> <br>
1280       <var>when-etag-matches</var>
1281       <var>unless-etag-matches</var> <br>
1282       <var>when-modified-since</var>
1283       <var>unless-modified-since</var> <br>
1284       <var>metadata</var> <var>public</var> <var>precondition-errors</var>
1285       <var>credentials</var>
1286     </span>
1287     <span class='result'>=> |</span>
1288   </div>
1289
1290   <blockquote class='description'>
1291     <p>Copies the object identified by <var>from-bucket</var>
1292     and <var>from-key</var> to a new location identified by
1293     <var>to-bucket</var> and <var>to-key</var>.
1294
1295     If <var>to-bucket</var> is NIL, <var>from-bucket</var> is used as
1296     the target. If <var>to-key</var> is nil, <var>from-key</var> is
1297     used as the target. An error is signaled if both <var>to-bucket</var> and
1298     <var>to-key</var> are NIL.
1299
1300     <p><var>access-policy</var> and <var>public</var> have the same
1301       effect on the target object as
1302       in <a href='#put-object'><tt>PUT-OBJECT</tt></a>.
1303
1304     <p>The precondition arguments <var>when-etag-matches</var>, <var>unless-etag-matches</var>,
1305     <var>when-modified-since</var>, and <var>unless-modified-since</var> work the same way they
1306     do in <a href='#get-object'><tt>GET-OBJECT</tt></a>, but with one difference: if <var>precondition-errors</var> is
1307     <i>true</i>, an <code>PRECONDITION-FAILED</code> error is signaled
1308     when a precondition does not hold, instead of returning NIL.
1309
1310     <p>If <var>metadata</var> is explicitly provided, it follows the
1311     same behavior as
1312     with <a href='#put-object'><tt>PUT-OBJECT</tt></a>. Passing NIL
1313     means that the new object has no metadata. Otherwise, the metadata
1314     is copied from the original object.
1315   </blockquote>
1316 </div>
1317
1318 <div class='item'>
1319   <div class='type'><a name='delete-object'>[Function]</a></div>
1320   <div class='signature'>
1321     <code class='name'>delete-object</code>
1322     <span class='args'>
1323       <var>bucket</var>
1324       <var>key</var>
1325       <code class='llkw'>&amp;key</code>
1326       <var>credentials</var>
1327     </span>
1328     <span class='result'>=> |</span>
1329   </div>
1330
1331   <blockquote class='description'>
1332     <p>Deletes the object identified by <var>bucket</var>
1333       and <var>key</var>.
1334     <p>If <var>bucket</var> is a valid bucket for
1335       which you have delete access granted, S3 will always return a success
1336       response, even if <var>key</var> does not reference an existing
1337       object.
1338   </blockquote>
1339 </div>
1340
1341 <div class='item'>
1342   <div class='type'><a name='delete-objects'>[Function]</a></div>
1343   <div class='signature'>
1344     <code class='name'>delete-objects</code>
1345     <span class='args'>
1346       <var>bucket</var>
1347       <var>keys</var>
1348       <code class='llkw'>&amp;key</code>
1349       <var>credentials</var>
1350     </span>
1351     <span class='result'>=> |</span>
1352   </div>
1353
1354   <blockquote class='description'>
1355     <p>Deletes <var>keys</var>, which should be a sequence of keys,
1356     from <var>bucket</var>.
1357   </blockquote>
1358 </div>
1359
1360 <div class='item'>
1361   <div class='type'><a name='delete-all-objects'>[Function]</a></div>
1362   <div class='signature'>
1363     <code class='name'>delete-all-objects</code>
1364     <span class='args'>
1365       <var>bucket</var>
1366       <code class='llkw'>&amp;key</code>
1367       <var>credentials</var>
1368     </span>
1369     <span class='result'>=> <var>count</var></span>
1370   </div>
1371
1372   <blockquote class='description'>
1373     <p>Deletes all objects in <var>bucket</var> and returns the count
1374       of objects deleted.
1375   </blockquote>
1376 </div>
1377
1378
1379 <div class='item'>
1380   <div class='type'><a name='object-metadata'>[Function]</a></div>
1381   <div class='signature'>
1382     <code class='name'>object-metadata</code>
1383     <span class='args'>
1384       <var>bucket</var>
1385       <var>key</var>
1386       <code class='llkw'>&amp;key</code>
1387       <var>credentials</var>
1388     </span>
1389     <span class='result'>=> <var>metadata-alist</var></span>
1390   </div>
1391
1392   <blockquote class='description'>
1393     <p>Returns the metadata for the object identified by <var>bucket</var> and <var>key</var>, or
1394     NIL if there is no metadata. For example:
1395
1396 <pre class='code'>
1397   * <b>(put-string "Hadjaha!" "zs3-demo" "hadjaha.txt" :metadata (parameters-alist :language "Swedish"))</b>
1398   => #&lt;RESPONSE 200 "OK" {1003BD2841}>
1399
1400   * <b>(object-metadata "zs3-demo" "hadjaha.txt")</b>
1401   => ((:LANGUAGE . "Swedish"))
1402 </pre>
1403
1404   </blockquote>
1405 </div>
1406
1407
1408 <a name='access-control'><h3>Access Control</h3></a>
1409
1410 <p>Each S3 resource has an associated access control list that is
1411   created automatically when the resource is created. The access
1412   control list specifies the resource owner and a list of permission
1413   grants.
1414
1415 <p>Grants consist of a permission and a grantee. The permission must
1416   be one of <code class='kw'>:READ</code>, <code class='kw'>:WRITE</code>,
1417   <code class='kw'>:READ-ACL</code>, <code class='kw'>:WRITE-ACL</code>,
1418   or <code class='kw'>:FULL-CONTROL</code>. The grantee should be a
1419   person object, an acl-group object, or an acl-email object.
1420
1421 <p>ZS3 has several functions that assist in reading, modifying, and
1422   storing access control lists.
1423
1424
1425 <div class='item'>
1426   <div class='type'><a name='get-acl'>[Function]</a></div>
1427   <div class='signature'>
1428     <code class='name'>get-acl</code>
1429     <span class='args'>
1430       <code class='llkw'>&amp;key</code>
1431       <var>bucket</var>
1432       <var>key</var>
1433       <var>credentials</var>
1434     </span>
1435     <span class='result'>=> <var>owner</var>, <var>grants</var></span>
1436   </div>
1437
1438   <blockquote class='description'>
1439     <p>Returns the owner and grant list for a resource as
1440     multiple values.
1441   </blockquote>
1442 </div>
1443
1444
1445 <div class='item'>
1446   <div class='type'><a name='put-acl'>[Function]</a></div>
1447   <div class='signature'>
1448     <code class='name'>put-acl</code>
1449     <span class='args'>
1450       <var>owner</var> <var>grants</var>
1451       <code class='llkw'>&amp;key</code>
1452       <var>bucket</var>
1453       <var>key</var>
1454       <var>credentials</var>
1455     </span>
1456     <span class='result'>=> |</span>
1457   </div>
1458
1459   <blockquote class='description'>
1460     <p>Sets the owner and grant list of a resource.
1461   </blockquote>
1462 </div>
1463
1464
1465 <div class='item'>
1466   <div class='type'><a name='grant'>[Function]</a></div>
1467   <div class='signature'>
1468     <code class='name'>grant</code>
1469     <span class='args'>
1470       <var>permission</var>
1471       <code class='llkw'>&amp;key</code>
1472       <var>to</var>
1473     </span>
1474     <span class='result'>=> <var>grant</var></span>
1475   </div>
1476
1477   <blockquote class='description'>
1478     <p>Returns a grant object that represents a permission (one of <code class='kw'>:READ</code>, <code class='kw'>:WRITE</code>,
1479       <code class='kw'>:READ-ACL</code>, <code class='kw'>:WRITE-ACL</code>,
1480       or <code class='kw'>:FULL-CONTROL</code>) for the
1481       grantee <var>to</var>. For example:
1482
1483 <pre class='code'>
1484   * <b>(grant :full-control :to (<a href='#acl-email'>acl-email</a> "bob@example.com"))</b>
1485   => #&lt;GRANT :FULL-CONTROL to "bob@example.com">
1486
1487   * <b>(grant :read :to <a href='#*all-users*'>*all-users*</a>)</b>
1488   => #&lt;GRANT :READ to "AllUsers">
1489 </pre>
1490
1491     <p>It can be used to create or modify a grant list for use
1492     with <a href='#put-acl'><tt>PUT-ACL</tt></a>.
1493   </blockquote>
1494 </div>
1495
1496
1497 <div class='item'>
1498   <div class='type'><a name='acl-eqv'>[Function]</a></div>
1499   <div class='signature'>
1500     <code class='name'>acl-eqv</code>
1501     <span class='args'>
1502       <var>a</var> <var>b</var>
1503     </span>
1504     <span class='result'>=> <var>boolean</var></span>
1505   </div>
1506
1507   <blockquote class='description'>
1508     <p>Returns <i>true</i> if <var>a</var> and <var>b</var> are equivalent
1509       ACL-related objects (person, group, email, or grant).
1510   </blockquote>
1511 </div>
1512
1513
1514 <div class='item'>
1515   <div class='type'><a name='*all-users*'>[Special variable]</a></div>
1516   <div class='signature'>
1517     <code class='name'>*all-users*</code>
1518   </div>
1519
1520   <blockquote class='description'>
1521     <p>This acl-group includes all users, including unauthenticated
1522     clients.
1523   </blockquote>
1524 </div>
1525
1526
1527 <div class='item'>
1528   <div class='type'><a name='*aws-users*'>[Special variable]</a></div>
1529   <div class='signature'>
1530     <code class='name'>*aws-users*</code>
1531   </div>
1532
1533   <blockquote class='description'>
1534     <p>This acl-group object includes only users that have an
1535     Amazon Web Services account.
1536   </blockquote>
1537 </div>
1538
1539
1540 <div class='item'>
1541   <div class='type'><a name='*log-delivery*'>[Special variable]</a></div>
1542   <div class='signature'>
1543     <code class='name'>*log-delivery*</code>
1544   </div>
1545
1546   <blockquote class='description'>
1547     <p>This acl-group object includes the S3 system user that creates
1548       logfile objects. See
1549       also <a href='#enable-logging-to'><tt>ENABLE-LOGGING-TO</tt></a>.
1550   </blockquote>
1551 </div>
1552
1553
1554 <div class='item'>
1555   <div class='type'><a name='acl-email'>[Function]</a></div>
1556   <div class='signature'>
1557     <code class='name'>acl-email</code>
1558     <span class='args'>
1559       <var>email-address</var>
1560     </span>
1561     <span class='result'>=> <var>acl-email</var></span>
1562   </div>
1563
1564   <blockquote class='description'>
1565     <p>Returns an acl-email object, which can be used as a grantee for
1566       <a href='#grant'><tt>GRANT</tt></a>.
1567   </blockquote>
1568 </div>
1569
1570
1571 <div class='item'>
1572   <div class='type'><a name='acl-person'>[Function]</a></div>
1573   <div class='signature'>
1574     <code class='name'>acl-person</code>
1575     <span class='args'>
1576       <var>id</var>
1577       <code class='llkw'>&amp;optional</code>
1578       <var>display-name</var>
1579     </span>
1580     <span class='result'>=> <var>acl-person</var></span>
1581   </div>
1582
1583   <blockquote class='description'>
1584     <p>Returns an acl-person object for use as a resource owner (for
1585       <a href='#put-acl'><tt>PUT-ACL</tt></a>) or as a grantee
1586       (for <a href='#grant'><tt>GRANT</tt></a>). <var>id</var> must be
1587       a string representing the person's Amazon AWS canonical ID; for
1588       information about getting the canonical ID, see
1589       the <a href="http://docs.amazonwebservices.com/AmazonS3/2006-03-01/S3_ACLs.html">Access
1590       Control Lists</a> in the Amazon S3 developer
1591       documentation. If <var>display-name</var> is provided, it is
1592       used only for printing the object in Lisp; it is ignored when
1593       passed to S3.
1594   </blockquote>
1595 </div>
1596
1597
1598 <div class='item'>
1599   <div class='type'><a name='me'>[Function]</a></div>
1600   <div class='signature'>
1601     <code class='name'>me</code>
1602     <span class='args'>
1603       <code class='llkw'>&amp;key</code>
1604       <var>credentials</var>
1605     </span>
1606     <span class='result'>=> <var>acl-person</var></span>
1607   </div>
1608
1609   <blockquote class='description'>
1610     <p>Returns the acl-person object associated with the current
1611       credentials.
1612
1613     <p>This data requires a S3 request, but the result is always the
1614     same per credentials and is cached.
1615   </blockquote>
1616 </div>
1617
1618
1619 <div class='item'>
1620   <div class='type'><a name='make-public'>[Function]</a></div>
1621   <div class='signature'>
1622     <code class='name'>make-public</code>
1623     <span class='args'>
1624       <code class='llkw'>&amp;key</code>
1625       <var>bucket</var>
1626       <var>key</var>
1627       <var>credentials</var>
1628     </span>
1629     <span class='result'>=> |</span>
1630   </div>
1631
1632   <blockquote class='description'>
1633     <p>Makes a resource publicly accessible, i.e. readable by
1634       the <a href='#*all-users*'><tt>*ALL-USERS*</tt></a> group.
1635   </blockquote>
1636 </div>
1637
1638
1639 <div class='item'>
1640   <div class='type'><a name='make-private'>[Function]</a></div>
1641   <div class='signature'>
1642     <code class='name'>make-private</code>
1643     <span class='args'>
1644       <code class='llkw'>&amp;key</code>
1645       <var>bucket</var>
1646       <var>key</var>
1647       <var>credentials</var>
1648     </span>
1649     <span class='result'>=> |</span>
1650   </div>
1651
1652   <blockquote class='description'>
1653     <p>Removes public access to a resource, i.e. removes all
1654       access grants for
1655       the <a href='#*all-users*'><tt>*ALL-USERS*</tt></a> group.
1656   </blockquote>
1657 </div>
1658
1659
1660
1661 <a name='access-logging'><h3>Access Logging</h3></a>
1662
1663 <p>S3 offers support for logging information about client
1664   requests. Logfile objects are delivered by a system user in
1665   the <a href='#*log-delivery*'><tt>*LOG-DELIVERY*</tt></a> group to a
1666   bucket of your choosing. For more information about S3 access
1667   logging and the logfile format, see
1668   the <a href="http://docs.amazonwebservices.com/AmazonS3/2006-03-01/ServerLogs.html">Server
1669   Access Logging</a> in the Amazon S3
1670   developer documentation.
1671
1672 <div class='item'>
1673   <div class='type'><a name='enable-logging-to'>[Function]</a></div>
1674   <div class='signature'>
1675     <code class='name'>enable-logging-to</code>
1676     <span class='args'>
1677       <var>bucket</var>
1678       <code class='llkw'>&amp;key</code>
1679       <var>credentials</var>
1680     </span>
1681     <span class='result'>=> |</span>
1682   </div>
1683
1684   <blockquote class='description'>
1685     Adds the necessary permission grants to <var>bucket</var> to allow
1686     S3 to write logfile objects into it.
1687   </blockquote>
1688 </div>
1689
1690
1691 <div class='item'>
1692   <div class='type'><a name='disable-logging-to'>[Function]</a></div>
1693   <div class='signature'>
1694     <code class='name'>disable-logging-to</code>
1695     <span class='args'>
1696       <var>bucket</var>
1697       <code class='llkw'>&amp;key</code>
1698       <var>credentials</var>
1699     </span>
1700     <span class='result'>=> |</span>
1701   </div>
1702
1703   <blockquote class='description'>
1704     <p>Changes the access control list of <var>bucket</var> to remove
1705     all grants for
1706     the <a href='#*log-delivery*'><tt>*LOG-DELIVERY*</tt></a> group.
1707   </blockquote>
1708 </div>
1709
1710
1711 <div class='item'>
1712   <div class='type'><a name='enable-logging'>[Function]</a></div>
1713   <div class='signature'>
1714     <code class='name'>enable-logging</code>
1715     <span class='args'>
1716       <var>bucket</var>
1717       <var>target-bucket</var>
1718       <var>target-prefix</var>
1719       <code class='llkw'>&amp;key</code>
1720       <var>target-grants</var>
1721       <var>credentials</var>
1722     </span>
1723     <span class='result'>=> |</span>
1724   </div>
1725
1726   <blockquote class='description'>
1727     <p>Enables logging of all requests
1728     involving <var>bucket</var>. Logfile objects are created in
1729       <var>target-bucket</var> and each logfile's key starts with
1730       <var>target-prefix</var>.
1731
1732     <p>When a new logfile is
1733       created, its list of access control grants is extended with
1734       <var>target-grants</var>, if any.
1735
1736     <p>If <var>target-bucket</var> does not have the necessary grants
1737     to allow logging, the grants are implicitly added by
1738     calling <a href='#enable-logging-to'><tt>ENABLE-LOGGING-TO</tt></a>.
1739   </blockquote>
1740 </div>
1741
1742
1743 <div class='item'>
1744   <div class='type'><a name='disable-logging'>[Function]</a></div>
1745   <div class='signature'>
1746     <code class='name'>disable-logging</code>
1747     <span class='args'>
1748       <var>bucket</var> <code class='llkw'>&amp;key</code> <var>credentials</var>
1749     </span>
1750     <span class='result'>=> |</span>
1751   </div>
1752
1753   <blockquote class='description'>
1754     Disables logging for <var>bucket</var>.
1755   </blockquote>
1756 </div>
1757
1758
1759 <div class='item'>
1760   <div class='type'><a name='logging-setup'>[Function]</a></div>
1761   <div class='signature'>
1762     <code class='name'>logging-setup</code>
1763     <span class='args'>
1764       <var>bucket</var>
1765       <code class='llkw'>&amp;key</code>
1766       <var>credentials</var>
1767     </span>
1768     <span class='result'>=> <var>target-bucket</var>,
1769       <var>target-prefix</var>,
1770       <var>target-grants</var></span>
1771   </div>
1772
1773   <blockquote class='description'>
1774     <p>If logging is enabled for <var>bucket</var>, returns the target
1775       bucket, target prefix, and target grants as multiple values.
1776   </blockquote>
1777 </div>
1778
1779
1780 <a name='misc'><h3>Miscellaneous Operations</h3></a>
1781
1782 <p>
1783
1784 <div class='item'>
1785   <div class='type'><a name='*use-ssl*'>[Special variable]</a></div>
1786   <div class='signature'>
1787     <code class='name'>*use-ssl*</code>
1788   </div>
1789
1790   <blockquote class='description'>
1791     <p>When <i>true</i>, requests to S3 are sent via HTTPS. The
1792       default is NIL.
1793   </blockquote>
1794 </div>
1795
1796
1797 <div class='item'>
1798   <div class='type'><a name='make-post-policy'>[Function]</a></div>
1799   <div class='signature'>
1800     <code class='name'>make-post-policy</code>
1801     <span class='args'>
1802       <code class='llkw'>&amp;key</code>
1803       <var>expires</var>
1804       <var>conditions</var>
1805       <var>credentials</var>
1806     </span>
1807     <span class='result'>=> <var>policy</var>, <var>signature</var></span>
1808   </div>
1809
1810   <blockquote class='description'>
1811     <p>Returns an encoded HTML POST form policy and its signature as
1812     multiple values. The policy can be used to conditionally allow any
1813     user to put objects into S3.
1814
1815     <p><var>expires</var> must be a universal time after which
1816     the policy is no longer accepted.
1817
1818     <p><var>conditions</var> must be a list of conditions that the
1819     posted form fields must satisfy. Each condition is a list of a
1820     condition keyword, a form field name, and the form field
1821     value. For example, the following are all valid conditions:
1822
1823     <p>
1824       <ul>
1825         <li> <code>(:starts-with "key" "uploads/")</code>
1826         <li> <code>(:eq "bucket" "user-uploads")</code>
1827         <li> <code>(:eq "acl" "public-read")</code>
1828         <li> <code>(:range "content-length-range" 1 10000)</code>
1829       </ul>
1830
1831     <p>These conditions are converted into a post policy description,
1832     base64-encoded, and returned as <var>policy</var>. The signature
1833     is returned as <var>signature</var>. These values can then be
1834     embedded in an HTML form and used to allow direct browser uploads.
1835
1836     <p>For example, if <var>policy</var> is
1837     "YSBwYXRlbnRseSBmYWtlIHBvbGljeQ==" and the policy signature is
1838     "ZmFrZSBzaWduYXR1cmU=", you could construct a form like this:
1839
1840 <p class='html'>
1841 &lt;form action="http://user-uploads.s3.amazonaws.com/" method="post" enctype="multipart/form-data"><br>
1842 &lt;input type="input" name="key" value="uploads/fun.jpg"><br>
1843 &lt;input type=hidden name="acl" value="public-read"><br>
1844 &lt;input type=hidden name="AWSAccessKeyId" value="8675309JGT9876430310"><br>
1845 &lt;input type=hidden name="Policy" value="YSBwYXRlbnRseSBmYWtlIHBvbGljeQ=="><br>
1846 &lt;input type=hidden name='Signature' value="ZmFrZSBzaWduYXR1cmU="><br>
1847 &lt;input name='file' type='file'><br>
1848 &lt;input type=submit value='Submit'><br>
1849 &lt;/form><br>
1850
1851    <p>For full, detailed documentation of browser-based POST uploads
1852    and policy documents,
1853    see <a href="http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingHTTPPOST.html">Browser-Based
1854    Uploads Using POST</a> in the Amazon S3 developer documentation.
1855   </blockquote>
1856 </div>
1857
1858
1859 <div class='item'>
1860   <div class='type'><a name='head'>[Function]</a></div>
1861   <div class='signature'>
1862     <code class='name'>head</code>
1863     <span class='args'>
1864       <code class='llkw'>&amp;key</code>
1865       <var>bucket</var>
1866       <var>key</var>
1867       <var>parameters</var>
1868       <var>credentials</var>
1869     </span>
1870     <span class='result'>=> <var>headers-alist</var>,
1871       <var>status-code</var>,
1872       <var>phrase</var></span>
1873   </div>
1874
1875   <blockquote class='description'>
1876     <p>Submits a HTTP HEAD request for the resource identified by
1877       <var>bucket</var> and optionally <var>key</var>. Returns the
1878       <a href='http://weitz.de/drakma/'>Drakma</a> headers, HTTP
1879       status code, and HTTP phrase as multiple values.
1880
1881     <p>When <var>parameters</var> is supplied, it should be an alist
1882       of keys and values to pass as GET request parameters. For
1883       example:
1884
1885 <pre class='code'>
1886   * <b>(head :bucket "zs3-demo" :parameters (<a href='http://cliki.net/parameters-alist?download'>parameters-alist</a> :max-keys 0))</b>
1887   => ((:X-AMZ-ID-2  . "...")
1888       (:X-AMZ-REQUEST-ID . "...")
1889       (:DATE . "Sat, 27 Sep 2008 19:00:35 GMT")
1890       (:CONTENT-TYPE . "application/xml")
1891       (:TRANSFER-ENCODING . "chunked")
1892       (:SERVER . "AmazonS3")
1893       (:CONNECTION . "close")),
1894       200,
1895       "OK"</pre>
1896   </blockquote>
1897 </div>
1898
1899
1900 <div class='item'>
1901   <div class='type'><a name='authorized-url'>[Function]</a></div>
1902   <div class='signature'>
1903     <code class='name'>authorized-url</code>
1904     <span class='args'>
1905       <code class='llkw'>&amp;key</code>
1906       <var>bucket</var>
1907       <var>key</var>
1908       <var>vhost</var>
1909       <var>expires</var>
1910       <var>ssl</var>
1911       <var>sub-resource</var>
1912       <var>credentials</var>
1913     </span>
1914     <span class='result'>=> <var>url</var></span>
1915   </div>
1916
1917   <blockquote class='description'>
1918     <p>Creates an URL that allows temporary access to a resource regardless
1919     of its ACL.
1920
1921     <p>If neither <var>bucket</var> nor <var>key</var> is specified, the top-level bucket listing
1922     is accessible. If <var>key</var> is not specified, listing the keys of <var>bucket</var> is
1923     accessible. If both <var>bucket</var> and key are <var>specified</var>, the object specified
1924     by <var>bucket</var> and <var>key</var> is accessible.
1925
1926     <p><var>expires</var> is required, and should be the integer
1927     universal time after which the URL is no longer valid.
1928
1929     <p><var>vhost</var> controls the construction of the
1930     url. If <var>vhost</var> is nil, the constructed URL refers to the
1931     bucket, if present, as part of the path. If <var>vhost</var>
1932     is <code class='kw'>:AMAZON</code>, the bucket name is used as a
1933     prefix to the Amazon hostname. If <var>vhost</var>
1934     is <code class='kw'>:FULL</code>, the bucket name becomes the full
1935     hostname of the url. For example:
1936
1937 <pre class='code'>
1938   * <b>(authorized-url :bucket "foo" :key "bar" :vhost nil)</b>
1939   =&gt; "http://s3.amazonaws.com/foo/bar?..."
1940
1941   * <b>(authorized-url :bucket "foo" :key "bar" :vhost :amazon)</b>
1942   =&gt; "http://foo.s3.amazonaws.com/bar?..."
1943
1944   * <b>(authorized-url :bucket "foo.example.com" :key "bar" :vhost :full)</b>
1945   =&gt;  "http://foo.example.com/bar?..."
1946 </pre>
1947
1948     <p>If <i>ssl</i> is <i>true</i>, the URL has "https" as the scheme,
1949     otherwise it has "http".
1950
1951     <p>If <i>sub-resource</i> is specified, it is used as part of the
1952     query string to access a specific sub-resource. Example Amazon
1953     sub-resources include "acl" for access to the ACL, "location" for
1954     location information, and "logging" for logging information. For
1955     more information about the various sub-resources, see the Amazon
1956     S3 developer documentation.
1957   </blockquote>
1958 </div>
1959
1960
1961 <div class='item'>
1962   <div class='type'><a name='resource-url'>[Function]</a></div>
1963   <div class='signature'>
1964     <code class='name'>resource-url</code>
1965     <span class='args'>
1966       <code class='llkw'>&amp;key</code>
1967       <var>bucket</var>
1968       <var>key</var>
1969       <var>vhost</var>
1970       <var>ssl</var>
1971       <var>sub-resource</var>
1972     </span>
1973     <span class='result'>=> <var>url</var></span>
1974   </div>
1975
1976   <blockquote class='description'>
1977     <p>Returns an URL that can be used to reference a resource. See
1978       <a href='#authorized-url'><tt>AUTHORIZED-URL</tt></a> for more
1979       info.
1980   </blockquote>
1981 </div>
1982
1983
1984 <a name='utility'><h3>Utility Functions</h3></a>
1985
1986 <p>
1987
1988 <div class='item'>
1989   <div class='type'><a name='octet-vector'>[Function]</a></div>
1990   <div class='signature'>
1991     <code class='name'>octet-vector</code>
1992     <span class='args'>
1993       <code class='llkw'>&amp;rest</code>
1994       <var>octets</var>
1995     </span>
1996     <span class='result'>=> <var>octet-vector</var></span>
1997   </div>
1998
1999   <blockquote class='description'>
2000     <p>Returns a vector of type
2001       <code>(simple-array&nbsp;(unsigned-byte&nbsp;8)&nbsp;(*))</code> initialized with <var>octets</var>.
2002   </blockquote>
2003 </div>
2004
2005
2006 <div class='item'>
2007   <div class='type'><a name='now+'>[Function]</a></div>
2008   <div class='signature'>
2009     <code class='name'>now+</code>
2010     <span class='args'>
2011       <var>delta</var>
2012     </span>
2013     <span class='result'>=> <var>universal-time</var></span>
2014   </div>
2015
2016   <blockquote class='description'>
2017     <p>Returns a universal time that represents the current time
2018       incremented by <var>delta</var> seconds. It's useful for passing
2019       as the <code class='kw'>:EXPIRES</code> parameter to functions
2020       like <a href='#put-object'><tt>PUT-OBJECT</tt></a>
2021       and <a href='#authorized-url'><tt>AUTHORIZED-URL</tt></a>.
2022   </blockquote>
2023 </div>
2024
2025
2026 <div class='item'>
2027   <div class='type'><a name='now-'>[Function]</a></div>
2028   <div class='signature'>
2029     <code class='name'>now-</code>
2030     <span class='args'>
2031       <var>delta</var>
2032     </span>
2033     <span class='result'>=> <var>universal-time</var></span>
2034   </div>
2035
2036   <blockquote class='description'>
2037     <p>Like <a href='#now+'><tt>NOW+</tt></a>, but decrements the
2038       current time instead of incrementing it.
2039   </blockquote>
2040 </div>
2041
2042
2043 <div class='item'>
2044   <div class='type'><a name='file-etag'>[Function]</a></div>
2045   <div class='signature'>
2046     <code class='name'>file-etag</code>
2047     <span class='args'>
2048       <var>pathname</var>
2049     </span>
2050     <span class='result'>=> <var>etag</var></span>
2051   </div>
2052
2053   <blockquote class='description'>
2054     <p>Returns the etag of <var>pathname</var>. This can be useful for the
2055       conditional arguments
2056       <code class='kw'>:WHEN-ETAG-MATCHES</code> and
2057       <code class='kw'>:UNLESS-ETAG-MATCHES</code>
2058       in <a href='#get-object'><tt>GET-OBJECT</tt></a>
2059       and <a href='#copy-object'><tt>COPY-OBJECT</tt></a>.
2060   </blockquote>
2061 </div>
2062
2063
2064 <div class='item'>
2065   <div class='type'><a name='parameters-alist'>[Function]</a></div>
2066   <div class='signature'>
2067     <code class='name'>parameters-alist</code>
2068     <span class='args'>
2069       <code class='llkw'>&amp;rest</code>
2070       <var>parameters</var>
2071       <code class='llkw'>&amp;key</code>
2072       <code class='llkw'>&amp;allow-other-keys</code>
2073     </span>
2074     <span class='result'>=> <var>alist</var></span>
2075   </div>
2076
2077   <blockquote class='description'>
2078     <p>Returns an alist based on all keyword arguments passed to the
2079       function. Keywords are converted to their lowercase symbol name and
2080       values are converted to strings. For example:
2081
2082 <pre class='code'>
2083   * <b>(parameters-alist :name "Bob" :age 21)</b>
2084   => (("name" . "Bob") ("age" . "21"))
2085 </pre>
2086
2087     <p>This can be used to construct Amazon metadata alists
2088     for <a href='#put-object'><tt>PUT-OBJECT</tt></a>
2089     and <a href='#copy-object'><tt>COPY-OBJECT</tt></a>, or request
2090     parameters in <a href='#head'><tt>HEAD</tt></a>.
2091
2092   </blockquote>
2093 </div>
2094
2095
2096
2097 <div class='item'>
2098   <div class='type'><a name='clear-redirects'>[Function]</a></div>
2099   <div class='signature'>
2100     <code class='name'>clear-redirects</code>
2101     <span class='args'>
2102     </span>
2103     <span class='result'>=> |</span>
2104   </div>
2105
2106   <blockquote class='description'>
2107     <p>Clear ZS3's internal cache of redirections.
2108
2109     <p>Most ZS3 requests are submitted against the Amazon S3 endpoint
2110       "s3.amazonaws.com". Some requests, however, are permanently
2111       redirected by S3 to new endpoints. ZS3 maintains an internal cache
2112       of permanent redirects, but it's possible for that cache to get
2113       out of sync if external processes alter the bucket structure
2114
2115     <p>For example, if the bucket "eu.zs3" is created with a EU
2116       location constraint, S3 will respond to requests to that bucket
2117       with a permanent redirect to "eu.zs3.s3.amazonaws.com", and ZS3
2118       will cache that redirect information. But if the bucket is
2119       deleted and recreated by a third party, the redirect might no
2120       longer be necessary.
2121   </blockquote>
2122 </div>
2123
2124
2125 <a name='cloudfront'><h2>CloudFront</h2>
2126
2127 <p>CloudFront functions allow the creation and manipulation of
2128   distributions. In ZS3, distributions are represented by objects that
2129   reflect the state of a distributon at some point in time. It's
2130   possible for the distribution to change behind the scenes without
2131   notice, e.g. when a distribution's <a href='#status'>status</a> is
2132   updated from "InProgress" to "Deployed".
2133
2134   <p>The
2135   functions <a href='#enable'><tt>ENABLE</tt></a>, <a href='#disable'><tt>DISABLE</tt></a>, <a href='#ensure-cname'><tt>ENSURE-CNAME</tt></a>,
2136   <a href='#remove-cname'><tt>REMOVE-CNAME</tt></a>,
2137   and <a href='#set-comment'><tt>SET-COMMENT</tt></a> are designed so
2138   that regardless of the state of the distribution provided, after the
2139   function completes, the new state of the distribution will reflect
2140   the desired update. The
2141   functions <a href='#status'><tt>STATUS</tt></a>, <a href='#cnames'><tt>CNAMES</tt></a>,
2142   and
2143   <a href='#enabledp'><tt>ENABLEDP</tt></a> do not automatically
2144   refresh the object and therefore might reflect outdated
2145   information. To ensure the object has the most recent information,
2146   use <a href='#refresh'><tt>REFRESH</tt></a>. For example, to fetch
2147   the current, live status, use <tt>(status (refresh
2148   distribution))</tt>.
2149
2150
2151
2152 <div class='item'>
2153   <div class='type'><a name='all-distributions'>[Function]</a></div>
2154   <div class='signature'>
2155     <code class='name'>all-distributions</code>
2156     <span class='args'>
2157     </span>
2158     <span class='result'>=> |</span>
2159   </div>
2160
2161   <blockquote class='description'>
2162     <p>Returns a list of all distributions.
2163   </blockquote>
2164 </div>
2165
2166 <div class='item'>
2167   <div class='type'><a name='create-distribution'>[Function]</a></div>
2168   <div class='signature'>
2169     <code class='name'>create-distribution</code>
2170     <span class='args'>
2171       <var>bucket-name</var>
2172       <code class='llkw'>&amp;key</code>
2173       <var>cnames</var>
2174       <var>enabled</var>
2175       <var>comment</var>
2176     </span>
2177     <span class='result'>=> <var>distribution</var></span>
2178   </div>
2179
2180   <blockquote class='description'>
2181     Creates and returns a new distribution object that will cache
2182     objects from the bucket named
2183     by <var>bucket-name</var>.
2184
2185     <p>If <var>cnames</var> is provided, it is taken as a designator
2186     for a list of additional domain names that can be used to access
2187     the distribution.
2188
2189     <p>If <var>enabled</var> is NIL, the distribution is initially
2190       created in a disabled state. The default value is is T.
2191
2192     <p>If <var>comment</var> is provided, it becomes part of the newly
2193       created distribution.
2194   </blockquote>
2195 </div>
2196
2197 <div class='item'>
2198   <div class='type'><a name='delete-distribution'>[Function]</a></div>
2199   <div class='signature'>
2200     <code class='name'>delete-distribution</code>
2201     <span class='args'>
2202       <var>distribution</var>
2203     </span>
2204     <span class='result'>=> |</span>
2205   </div>
2206
2207   <blockquote class='description'>
2208     <p>Deletes <var>distribution</var>. Distributions must be disabled
2209       before deletion; see <a href='#disable'><tt>DISABLE</tt></a>.
2210   </blockquote>
2211 </div>
2212
2213
2214 <div class='item'>
2215   <div class='type'><a name='refresh'>[Function]</a></div>
2216   <div class='signature'>
2217     <code class='name'>refresh</code>
2218     <span class='args'>
2219       <var>distribution</var>
2220     </span>
2221     <span class='result'>=> <var>distribution</var></span>
2222   </div>
2223
2224   <blockquote class='description'>
2225     <p>Queries Amazon for the latest information
2226     regarding <var>distribution</var> and destructively modifies the
2227     instance with the new information. Returns its argument.
2228   </blockquote>
2229 </div>
2230
2231
2232 <div class='item'>
2233   <div class='type'><a name='enable'>[Function]</a></div>
2234   <div class='signature'>
2235     <code class='name'>enable</code>
2236     <span class='args'>
2237       <var>distribution</var>
2238     </span>
2239     <span class='result'>=> |</span>
2240   </div>
2241
2242   <blockquote class='description'>
2243     <p>Enables <var>distribution</var>.
2244   </blockquote>
2245 </div>
2246
2247
2248 <div class='item'>
2249   <div class='type'><a name='disable'>[Function]</a></div>
2250   <div class='signature'>
2251     <code class='name'>disable</code>
2252     <span class='args'>
2253       <var>distribution</var>
2254     </span>
2255     <span class='result'>=> |</span>
2256   </div>
2257
2258   <blockquote class='description'>
2259     <p>Disables <var>distribution</var>.
2260   </blockquote>
2261 </div>
2262
2263
2264 <div class='item'>
2265   <div class='type'><a name='ensure-cname'>[Function]</a></div>
2266   <div class='signature'>
2267     <code class='name'>ensure-cname</code>
2268     <span class='args'>
2269       <var>distribution</var>
2270       <var>cname</var>
2271     </span>
2272     <span class='result'>=> |</span>
2273   </div>
2274
2275   <blockquote class='description'>
2276     <p>Adds <var>cname</var> to the CNAMEs of <var>distribution</var>,
2277       if necessary.
2278   </blockquote>
2279 </div>
2280
2281 <div class='item'>
2282   <div class='type'><a name='remove-cname'>[Function]</a></div>
2283   <div class='signature'>
2284     <code class='name'>remove-cname</code>
2285     <span class='args'>
2286       <var>distribution</var>
2287       <var>cname</var>
2288     </span>
2289     <span class='result'>=> |</span>
2290   </div>
2291
2292   <blockquote class='description'>
2293     <p>Removes <var>cname</var> from the CNAMEs of <var>distribution</var>.
2294   </blockquote>
2295 </div>
2296
2297
2298 <div class='item'>
2299   <div class='type'><a name='set-comment'>[Function]</a></div>
2300   <div class='signature'>
2301     <code class='name'>set-comment</code>
2302     <span class='args'>
2303       <var>distribution</var>
2304       <var>comment</var>
2305     </span>
2306     <span class='result'>=> |</span>
2307   </div>
2308
2309   <blockquote class='description'>
2310     <p>Sets the comment of <var>distribution</var> to <var>comment</var>.
2311   </blockquote>
2312 </div>
2313
2314
2315 <div class='item'>
2316   <div class='type'><a name='distributions-for-bucket'>[Function]</a></div>
2317   <div class='signature'>
2318     <code class='name'>distributions-for-bucket</code>
2319     <span class='args'>
2320       <var>bucket-name</var>
2321     </span>
2322     <span class='result'>=> |</span>
2323   </div>
2324
2325   <blockquote class='description'>
2326     <p>Returns a list of distributions that
2327       have <var>bucket-name</var> as the origin bucket.
2328   </blockquote>
2329 </div>
2330
2331
2332 <div class='item'>
2333   <div class='type'><a name='distribution-error'>[Condition]</a></div>
2334   <div class='signature'>
2335     <code class='name'>distribution-error</code>
2336   </div>
2337
2338   <blockquote class='description'>
2339     <p>All errors signaled as a result of a CloudFront request error
2340       are subtypes of <tt>distribution-error</tt>.
2341   </blockquote>
2342 </div>
2343
2344
2345 <div class='item'>
2346   <div class='type'><a name='distribution-not-disabled'>[Condition]</a></div>
2347   <div class='signature'>
2348     <code class='name'>distribution-not-disabled</code>
2349   </div>
2350
2351   <blockquote class='description'>
2352     <p>Distributions must be fully disabled before they are
2353       deleted. If they have not been disabled, or the status of the
2354       distribution is still
2355       "InProgress", <tt>distribution-not-disabled</tt> is signaled.
2356   </blockquote>
2357 </div>
2358
2359
2360 <div class='item'>
2361   <div class='type'><a name='cname-already-exists'>[Condition]</a></div>
2362   <div class='signature'>
2363     <code class='name'>cname-already-exists</code>
2364   </div>
2365
2366   <blockquote class='description'>
2367     <p>A CNAME may only appear on one distribution. If you attempt to
2368       add a CNAME to a distribution that is already present on some
2369       other distribution, <tt>cname-already-exists</tt> is signaled.
2370   </blockquote>
2371 </div>
2372
2373
2374 <div class='item'>
2375   <div class='type'><a name='too-many-distributions'>[Condition]</a></div>
2376   <div class='signature'>
2377     <code class='name'>too-many-distributions</code>
2378   </div>
2379
2380   <blockquote class='description'>
2381     <p>If creating a new distribution
2382       via <a href='#create-distribution'><tt>CREATE-DISTRIBUTION</tt></a>
2383       would exceed the account limit of total distributions,
2384       <tt>too-many-distributions</tt> is signaled.
2385   </blockquote>
2386 </div>
2387
2388
2389 <div class='item'>
2390   <div class='type'><a name='status'>[Function]</a></div>
2391   <div class='signature'>
2392     <code class='name'>status</code>
2393     <span class='args'>
2394       <var>distribution</var>
2395     </span>
2396     <span class='result'>=> <var>status</var></span>
2397   </div>
2398
2399   <blockquote class='description'>
2400     <p>Returns a string describing the status
2401       of <var>distribution</var>. The status is either "InProgress",
2402       meaning that the distribution's configuration has not fully
2403       propagated through the CloudFront system, or "Deployed".
2404   </blockquote>
2405 </div>
2406
2407
2408 <div class='item'>
2409   <div class='type'><a name='origin-bucket'>[Function]</a></div>
2410   <div class='signature'>
2411     <code class='name'>origin-bucket</code>
2412     <span class='args'>
2413       <var>distribution</var>
2414     </span>
2415     <span class='result'>=> <var>origin-bucket</var></span>
2416   </div>
2417
2418   <blockquote class='description'>
2419     <p>Returns the origin bucket for <var>distribution</var>. It is
2420       different from a normal ZS3 bucket name, because it has
2421       ".s3.amazonaws.com" as a suffix.
2422   </blockquote>
2423 </div>
2424
2425
2426 <div class='item'>
2427   <div class='type'><a name='domain-name'>[Function]</a></div>
2428   <div class='signature'>
2429     <code class='name'>domain-name</code>
2430     <span class='args'>
2431       <var>distribution</var>
2432     </span>
2433     <span class='result'>=> <var>domain-name</var></span>
2434   </div>
2435
2436   <blockquote class='description'>
2437     <p>Returns the domain name through which CloudFront-enabled access
2438       to a resource may be made.
2439   </blockquote>
2440 </div>
2441
2442
2443 <div class='item'>
2444   <div class='type'><a name='cnames'>[Function]</a></div>
2445   <div class='signature'>
2446     <code class='name'>cnames</code>
2447     <span class='args'>
2448       <var>distribution</var>
2449     </span>
2450     <span class='result'>=> <var>cnames</var></span>
2451   </div>
2452
2453   <blockquote class='description'>
2454     Returns a list of CNAMEs associated with <var>distribution</var>.
2455   </blockquote>
2456 </div>
2457
2458
2459 <div class='item'>
2460   <div class='type'><a name='enabledp'>[Function]</a></div>
2461   <div class='signature'>
2462     <code class='name'>enabledp</code>
2463     <span class='args'>
2464       <var>distribution</var>
2465     </span>
2466     <span class='result'>=> <var>boolean</var></span>
2467   </div>
2468
2469   <blockquote class='description'>
2470     <p>Returns <i>true</i> if <var>distribution</var> is enabled, NIL
2471       otherwise.
2472   </blockquote>
2473 </div>
2474
2475
2476 <div class='item'>
2477   <div class='type'><a name='invalidate-paths'>[Function]</a></div>
2478   <div class='signature'>
2479     <code class='name'>invalidate-paths</code>
2480     <span class='args'>
2481       <var>distribution</var>
2482       <var>paths</var>
2483     </span>
2484     <span class='result'>=> <var>invalidation</var></span>
2485   </div>
2486
2487   <blockquote class='description'>
2488     <p>Initiates the invalidation of resources identified
2489       by <var>paths</var> in <var>distribution</var>. <var>paths</var>
2490       should consist of key names that correspond to objects in the
2491       distribution's S3 bucket.
2492
2493     <p>The <var>invalidation</var> object reports on the status of the
2494       invalidation request. It can be queried
2495       with <a href='#status'><tt>STATUS</tt></a> and refreshed
2496       with <a href='#refresh'><tt>REFRESH</tt></a>.
2497
2498 <pre class='code'>
2499 * <b>(invalidate-paths distribution '("/css/site.css" "/js/site.js"))</b>
2500 #&lt;INVALIDATION "I1HJC711OFAVKO" [InProgress]>
2501 * <b>(progn (sleep 300) (refresh *))</b>
2502 #&lt;INVALIDATION "I1HJC711OFAVKO" [Completed]>
2503 </pre>
2504   </blockquote>
2505 </div>
2506
2507
2508
2509
2510 <a name='references'><h2>References</h2></a>
2511
2512   <ul>
2513     <li> Amazon, <a href="http://developer.amazonwebservices.com/connect/entry.jspa?externalID=123&categoryID=48">Amazon
2514    S3 Technical Documentation</a>
2515     <li> Amazon, <a href="http://developer.amazonwebservices.com/connect/entry.jspa?externalID=1876&categoryID=213">Amazon CloudFront Technical Documentation</a>
2516   </ul>
2517
2518
2519
2520
2521 <a name='acknowledgements'><h2>Acknowledgements</h2>
2522
2523   <p>Several people on <a href='http://freenode.net/'>freenode</a>
2524     #lisp pointed out typos and glitches in this
2525     documentation. Special thanks to Bart "_3b" Botta for providing a
2526     detailed documentation review that pointed out glitches,
2527     omissions, and overly confusing passages.
2528
2529   <p>James Wright corrected a problem with computing the string to
2530     sign and URL encoding.
2531
2532 <a name='feedback'><h2>Feedback</h2></a>
2533
2534   <p>If you have any questions or comments about ZS3, please email
2535   me, <a href='mailto:xach@xach.com'>Zach Beane</a>
2536
2537   <p>For ZS3 announcements and development discussion, please see the
2538   <a href="http://groups.google.com/group/zs3-devel">zs3-devel</a>
2539   mailing list.
2540
2541   <p><i>2010-09-03</i>
2542
2543  <p class='copyright'>Copyright &copy; 2008-2010 Zachary Beane, All Rights Reserved
2544
2545
2546 </div>
2547 </body>
2548 </html>
2549