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