doc/index.html

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