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.2.3, released on January 4th, 2014.
  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 <div class='item'>
 557   <div class='type'><a name='bucket-lifecycle'>[Function]</a></div>
 558   <div class='signature'>
 559     <code class='name'>bucket-lifecycle</code>
 560     <span class='args'>
 561       <var>bucket</var>
 562     </span>
 563     <span class='result'>=> <var>rules-list</var></span>
 564   </div>
 565
 566   <blockquote class='description'>
 567     <p>Returns a list of lifecycle rules
 568     for <var>bucket</var>. Signals a NO-SUCH-LIFECYCLE-CONFIGURATION
 569     error if the bucket has no lifecycle rules configured.
 570
 571     <p>Bucket lifecycle rules are used to control the automatic
 572       deletion of objects in a bucket. For more information about
 573       bucket lifecycle configuration,
 574       see <a href="http://docs.amazonwebservices.com/AmazonS3/latest/dev/ObjectExpiration.html">Object
 575       Expiration</a> in the Amazon S3 developer documentation.
 576   </blockquote>
 577 </div>
 578
 579 <div class='item'>
 580   <div class='type'><a name='setf-bucket-lifecycle'>[Function]</a></div>
 581   <div class='signature'>
 582     <code class='name'>(setf bucket-lifecycle)</code>
 583     <span class='args'>
 584       <var>rules</var> <var>bucket</var>
 585     </span>
 586     <span class='result'>=> |</span>
 587   </div>
 588
 589   <blockquote class='description'>
 590     <p>Sets the lifecycle configuration of <var>bucket</var> to the
 591     designator for a list of bucket lifecycle rules <var>rules</var>.
 592
 593     <p>To create a
 594     bucket lifecycle rule,
 595     use <a href='#lifecycle-rule'><tt>LIFECYCLE-RULE</tt></a>. For
 596     example, to automatically delete objects with keys matching a
 597     "logs/" prefix after 30 days:
 598
 599 <pre class='code'>
 600 (setf (bucket-lifecycle "my-bucket") (lifecycle-rule :prefix "logs/" :days 30))
 601 </pre>
 602
 603     <p>To delete a bucket's lifecycle configuration, use an empty list
 604     of rules, e.g.
 605
 606 <pre class='code'>
 607 (setf (bucket-lifecycle "my-bucket") nil)
 608 </pre>
 609
 610   </blockquote>
 611 </div>
 612
 613 <div class='item'>
 614   <div class='type'><a name='lifecycle-rule'>[Function]</a></div>
 615   <div class='signature'>
 616     <code class='name'>lifecycle-rule</code>
 617     <span class='args'>
 618       <code class='llkw'>&amp;key</code>
 619       <var>action</var>
 620       <var>prefix</var>
 621       <var>days</var>
 622       <var>date</var>
 623     </span>
 624     <span class='result'>=> <var>rule</var></span>
 625   </div>
 626
 627   <blockquote class='description'>
 628     <p>Creates a rule object suitable for passing
 629       to <a href='#setf-bucket-lifecycle'><tt>(SETF
 630           BUCKET-LIFECYCLE)</tt></a>.
 631
 632     <p><var>action</var> should be either <tt>:expire</tt> (the
 633     default) or <tt>:transition</tt>. For <tt>:expire</tt>, matching
 634     objects are deleted. For <tt>:transition</tt>, matching objects
 635     are transitioned to the GLACIER storage class. For more
 636     information about S3-to-Glacier object transition,
 637     see <a href="http://docs.amazonwebservices.com/AmazonS3/latest/dev/object-archival.html">Object
 638     Archival (Transition Objects to the Glacier Storage Class)</a> in
 639     the Amazon S3 Developer's Guide.
 640
 641     <p><var>prefix</var> is a string; all objects in a bucket with
 642         keys matching the prefix will be affected by the rule.
 643
 644     <p><var>days</var> is the number of days after which an object
 645     will be affected.
 646
 647     <p><var>date</var> is the date after which objects will be affected.
 648
 649     <p>Only one of <var>days</var> or <var>date</var> may be provided.
 650   </blockquote>
 651 </div>
 652
 653 <div class='item'>
 654   <div class='type'><a name='restore-object'>[Function]</a></div>
 655   <div class='signature'>
 656     <code class='name'>restore-object</code>
 657     <span class='args'>
 658       <var>bucket</var>
 659       <var>key</var>
 660       <code class='llkw'>&amp;body</code>
 661       <var>days</var>
 662       <var>credentials</var>
 663     </span>
 664     <span class='result'>=> |</span>
 665   </div>
 666
 667   <blockquote class='description'>
 668     <p>Initiates a restoration operation on the object identified
 669       by <var>bucket</var> and <var>key</var>.  A restoration
 670       operation can take several hours to complete. The restored
 671       object is temporarily stored with the reduced redundancy storage
 672       class. The status of the operation may monitored
 673       via <a href='#object-restoration-status'><tt>OBJECT-RESTORATION-STATUS</tt></a>.
 674
 675     <p><var>days</var> is the number of days for which the restored
 676       object should be avilable for normal retrieval before
 677       transitioning back to archival storage.
 678
 679     <p>Object restoration operation is only applicable to objects that
 680       have been transitioned to Glacier storage by the containing
 681       bucket's lifecycle configuration.
 682
 683     <p>For more information,
 684     see <a href="http://docs.amazonwebservices.com/AmazonS3/latest/API/RESTObjectPOSTrestore.html">POST
 685     Object restore</a> in the S3 documentation.
 686   </blockquote>
 687 </div>
 688
 689 <div class='item'>
 690   <div class='type'><a name='object-restoration-status'>[Function]</a></div>
 691   <div class='signature'>
 692     <code class='name'>object-restoration-status</code>
 693     <span class='args'>
 694       <var>bucket</var>
 695       <var>key</var>
 696       <code class='llkw'>&amp;key</code>
 697       <var>credentials</var>
 698     </span>
 699     <span class='result'>=> <var>status-string</var></span>
 700   </div>
 701
 702   <blockquote class='description'>
 703     <p>Returns a string describing the status of restoring the object
 704     identified by <var>bucket</var> and <var>key</var>. If no
 705     restoration is in progress, or the operation is not applicable,
 706     returns NIL.
 707   </blockquote>
 708 </div>
 709
 710
 711
 712 <a name='querying-buckets'><h3>Querying Buckets</h3></a>
 713
 714 <p>S3 has a flexible interface for querying a bucket for information
 715   about its contents. ZS3 supports this interface via
 716   <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a>,
 717    <a href='#continue-bucket-query'><tt>CONTINUE-BUCKET-QUERY</tt></a>,
 718    and related functions.
 719
 720 <div class='item'>
 721   <div class='type'><a name='query-bucket'>[Function]</a></div>
 722   <div class='signature'>
 723     <code class='name'>query-bucket</code>
 724     <span class='args'>
 725       <var>bucket</var>
 726       <code class='llkw'>&amp;key</code>
 727       <var>prefix</var>
 728       <var>marker</var>
 729       <var>max-keys</var>
 730       <var>delimiter</var>
 731       <var>credentials</var>
 732     </span>
 733     <span class='result'>=> <var>response</var></span>
 734   </div>
 735
 736   <blockquote class='description'>
 737     <p>Query <var>bucket</var> for key information. Returns a response
 738     object that has the result of the query. Response attributes are
 739     accessible via
 740       <a href='#bucket-name'><tt>BUCKET-NAME</tt></a>,
 741       <a href='#prefix'><tt>PREFIX</tt></a>,
 742       <a href='#marker'><tt>MARKER</tt></a>,
 743       <a href='#delimiter'><tt>DELIMITER</tt></a>,
 744       <a href='#truncatedp'><tt>TRUNCATEDP</tt></a>,
 745       <a href='#keys'><tt>KEYS</tt></a>, and
 746       <a href='#common-prefixes'><tt>COMMON-PREFIXES</tt></a>.
 747
 748     <p>Amazon might return fewer key objects than actually match the
 749       query parameters, based on <var>max-keys</var> or the result
 750       limit of 1000 key objects. In that
 751       case, <a href='#truncatedp'><tt>TRUNCATEDP</tt></a>
 752       for <var>response</var> is <i>true</i>, and
 753       <a href='#continue-bucket-query'><tt>CONTINUE-BUCKET-QUERY</tt></a>
 754       can be used with <var>response</var> be used to get successive
 755       responses for the query parameters.
 756
 757     <p>When <var>prefix</var> is supplied, only key objects with names
 758       that start with <var>prefix</var> will be returned
 759       in <var>response</var>.
 760
 761     <p>When <var>marker</var> is supplied, only key objects with names
 762       occurring lexically after <var>marker</var> will be returned in
 763       <var>response</var>.
 764
 765     <p>When <var>max-keys</var> is supplied, it places an inclusive
 766       upper limit on the number of key objects returned
 767       in <var>response</var>. Note that Amazon currently limits
 768       responses to at most 1000 key objects even
 769       if <var>max-keys</var> is greater than 1000.
 770
 771     <p>When <var>delimiter</var> is supplied, key objects that have
 772       the delimiter string after <var>prefix</var> in their names are
 773       not returned in the <a href='#keys'><tt>KEYS</tt></a> attribute
 774       of the response, but are instead accumulated into the
 775       <a href='#common-prefixes'><tt>COMMON-PREFIXES</tt></a>
 776       attribute of the response. For example:
 777 <pre class='code'>
 778   * <b>(all-keys "zs3-demo")</b>
 779   => #(#&lt;KEY "a" 4>
 780        #&lt;KEY "b/1" 4>
 781        #&lt;KEY "b/2" 4>
 782        #&lt;KEY "b/3" 4>
 783        #&lt;KEY "c/10" 4>
 784        #&lt;KEY "c/20" 4>
 785        #&lt;KEY "c/30" 4>)
 786
 787   * <b>(setf *response* (query-bucket "zs3-demo" :delimiter "/"))</b>
 788   => #&lt;BUCKET-LISTING "zs3-demo">
 789
 790   * <b>(values (keys *response*) (common-prefixes *response*))</b>
 791   => #(#&lt;KEY "a" 4>),
 792      #("b/"
 793        "c/")
 794
 795   * <b>(setf *response* (query-bucket "zs3-demo" :delimiter "/" :prefix "b/"))</b>
 796   => #&lt;BUCKET-LISTING "zs3-demo">
 797
 798   * <b>(values (keys *response*) (common-prefixes *response*))</b>
 799   => #(#&lt;KEY "b/1" 4>
 800        #&lt;KEY "b/2" 4>
 801        #&lt;KEY "b/3" 4>),
 802      #()</pre>
 803
 804     <p>For more information about bucket queries,
 805     see <a href="http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTBucketGET.html">GET
 806     Bucket</a> in the Amazon S3 developer documentation.
 807
 808   </blockquote>
 809
 810 </div>
 811
 812
 813 <div class='item'>
 814   <div class='type'><a name='continue-bucket-query'>[Function]</a></div>
 815   <div class='signature'>
 816     <code class='name'>continue-bucket-query</code>
 817     <span class='args'>
 818       <var>response</var>
 819     </span>
 820     <span class='result'>=> <var>response</var></span>
 821   </div>
 822
 823   <blockquote class='description'>
 824     <p>If <var>response</var> is a truncated response from a previous
 825     call to
 826       <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a>,
 827       continue-bucket-query returns the result of resuming the query at the
 828       truncation point. When there are no more results,
 829       continue-bucket-query returns NIL.
 830   </blockquote>
 831 </div>
 832
 833 <div class='item'>
 834   <div class='type'><a name='bucket-name'>[Function]</a></div>
 835   <div class='signature'>
 836     <code class='name'>bucket-name</code>
 837     <span class='args'>
 838       <var>response</var>
 839     </span>
 840     <span class='result'>=> <var>name</var></span>
 841   </div>
 842
 843   <blockquote class='description'>
 844     <p>Returns the name of the bucket used in the call
 845       to <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> that
 846       produced <var>response</var>.
 847   </blockquote>
 848 </div>
 849
 850
 851
 852
 853 <div class='item'>
 854   <div class='type'><a name='keys'>[Function]</a></div>
 855   <div class='signature'>
 856     <code class='name'>keys</code>
 857     <span class='args'>
 858       <var>response</var>
 859     </span>
 860     <span class='result'>=> <var>keys-vector</var></span>
 861   </div>
 862
 863   <blockquote class='description'>
 864     <p>Returns the vector of key objects in <var>response</var>. Key
 865     object attributes are accessible via
 866       <a href='#name'><tt>NAME</tt></a>,
 867       <a href='#size'><tt>SIZE</tt></a>,
 868       <a href='#etag'><tt>ETAG</tt></a>,
 869       <a href='#last-modified'><tt>LAST-MODIFIED</tt></a>,
 870       and <a href='#owner'><tt>OWNER</tt></a>.
 871   </blockquote>
 872 </div>
 873
 874
 875 <div class='item'>
 876   <div class='type'><a name='common-prefixes'>[Function]</a></div>
 877   <div class='signature'>
 878     <code class='name'>common-prefixes</code>
 879     <span class='args'>
 880       <var>response</var>
 881     </span>
 882     <span class='result'>=> <var>prefix-vector</var></span>
 883   </div>
 884
 885   <blockquote class='description'>
 886     <p>Returns a vector of common prefix strings, based on the
 887       delimiter argument of
 888       the <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> call that
 889       produced <var>response</var>.
 890   </blockquote>
 891 </div>
 892
 893
 894 <div class='item'>
 895   <div class='type'><a name='prefix'>[Function]</a></div>
 896   <div class='signature'>
 897     <code class='name'>prefix</code>
 898     <span class='args'>
 899       <var>response</var>
 900     </span>
 901     <span class='result'>=> <var>prefix-string</var></span>
 902   </div>
 903
 904   <blockquote class='description'>
 905     <p>Returns the prefix given to
 906     the <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> call that
 907     produced <var>response</var>. If present, all keys
 908     in <var>response</var> have <var>prefix-string</var> as a prefix.
 909   </blockquote>
 910 </div>
 911
 912 <div class='item'>
 913   <div class='type'><a name='marker'>[Function]</a></div>
 914   <div class='signature'>
 915     <code class='name'>marker</code>
 916     <span class='args'>
 917       <var>response</var>
 918     </span>
 919     <span class='result'>=> <var>marker</var></span>
 920   </div>
 921
 922   <blockquote class='description'>
 923     <p>Returns the marker given to
 924       the <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> call that
 925       produced <var>response</var>. If present,
 926       it lexically precedes all key names in the response.
 927   </blockquote>
 928 </div>
 929
 930 <div class='item'>
 931   <div class='type'><a name='delimiter'>[Function]</a></div>
 932   <div class='signature'>
 933     <code class='name'>delimiter</code>
 934     <span class='args'>
 935       <var>response</var>
 936     </span>
 937     <span class='result'>=> <var>delimiter</var></span>
 938   </div>
 939
 940   <blockquote class='description'>
 941     <p>Returns the delimiter used in
 942       the <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> call that
 943       produced <var>response</var>.
 944   </blockquote>
 945 </div>
 946
 947
 948 <div class='item'>
 949   <div class='type'><a name='truncatedp'>[Function]</a></div>
 950   <div class='signature'>
 951     <code class='name'>truncatedp</code>
 952     <span class='args'>
 953       <var>response</var>
 954     </span>
 955     <span class='result'>=> <var>boolean</var></span>
 956   </div>
 957
 958   <blockquote class='description'>
 959     <p>Returns <i>true</i> if <var>response</var> is truncated; that
 960     is, if there is more data to retrieve for a
 961     given <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a>
 962     query. <a href='#continue-bucket-query'><tt>CONTINUE-BUCKET-QUERY</tt></a>
 963     may be used to fetch more data.
 964   </blockquote>
 965 </div>
 966
 967
 968 <div class='item'>
 969   <div class='type'><a name='last-modified'>[Function]</a></div>
 970   <div class='signature'>
 971     <code class='name'>last-modified</code>
 972     <span class='args'>
 973       <var>key-object</var>
 974     </span>
 975     <span class='result'>=> <var>universal-time</var></span>
 976   </div>
 977
 978   <blockquote class='description'>
 979     <p>Returns a universal time representing the last modified time
 980     of <var>key-object</var>.
 981   </blockquote>
 982 </div>
 983
 984
 985 <div class='item'>
 986   <div class='type'><a name='etag'>[Function]</a></div>
 987   <div class='signature'>
 988     <code class='name'>etag</code>
 989     <span class='args'>
 990       <var>key-object</var>
 991     </span>
 992     <span class='result'>=> <var>etag-string</var></span>
 993   </div>
 994
 995   <blockquote class='description'>
 996     <p>Returns the etag for <var>key-object</var>.
 997   </blockquote>
 998 </div>
 999
1000
1001 <div class='item'>
1002   <div class='type'><a name='size'>[Function]</a></div>
1003   <div class='signature'>
1004     <code class='name'>size</code>
1005     <span class='args'>
1006       <var>key-object</var>
1007     </span>
1008     <span class='result'>=> <var>size</var></span>
1009   </div>
1010
1011   <blockquote class='description'>
1012     <p>Returns the size, in octets, of <var>key-object</var>.
1013   </blockquote>
1014 </div>
1015
1016
1017 <div class='item'>
1018   <div class='type'><a name='owner'>[Function]</a></div>
1019   <div class='signature'>
1020     <code class='name'>owner</code>
1021     <span class='args'>
1022       <var>key-object</var>
1023     </span>
1024     <span class='result'>=> <var>owner</var></span>
1025   </div>
1026
1027   <blockquote class='description'>
1028       <p>Returns the owner of <var>key-object</var>, or NIL if no owner
1029       information is available.
1030   </blockquote>
1031 </div>
1032
1033
1034 <div class='item'>
1035   <div class='type'><a name='storage-class'>[Function]</a></div>
1036   <div class='signature'>
1037     <code class='name'>storage-class</code>
1038     <span class='args'>
1039       <var>key-object</var>
1040     </span>
1041     <span class='result'>=> <var>storage-class</var></span>
1042   </div>
1043
1044   <blockquote class='description'>
1045     <p>Returns the storage class of <var>key-object</var>.
1046   </blockquote>
1047 </div>
1048
1049
1050
1051
1052
1053 <a name='object-ops'><h3>Operations on Objects</h3></a>
1054
1055 <p>Objects are the stored binary data in S3. Every object is uniquely
1056   identified by a bucket/key pair. ZS3 has several functions for
1057   storing and fetching objects, and querying object attributes.
1058
1059 <div class='item'>
1060   <div class='type'><a name='get-object'>[Function]</a></div>
1061   <div class='signature'>
1062     <code class='name'>get-object</code>
1063     <span class='args'>
1064       <var>bucket</var>
1065       <var>key</var>
1066       <code class='llkw'>&amp;key</code>
1067       <var>output</var> <br>
1068       <var>start</var> <var>end</var> <br>
1069       <var>when-modified-since</var> <var>unless-modified-since</var> <br>
1070       <var>when-etag-matches</var> <var>unless-etag-matches</var> <br>
1071       <var>if-exists</var> <var>string-external-format</var>
1072       <var>credentials</var>
1073     </span>
1074     <span class='result'>=> <var>object</var></span>
1075   </div>
1076
1077   <blockquote class='description'>
1078     <p>Fetch the object referenced by <var>bucket</var>
1079     and <var>key</var>. The secondary value of all successful requests
1080     is an alist of <a href='http://weitz.de/drakma/'>Drakma</a>-style
1081     response HTTP headers.
1082
1083     <p>If <var>output</var> is <code class='kw'>:VECTOR</code> (the
1084     default), the object's octets are returned in a vector.
1085
1086     <p>If <var>output</var> is <code class='kw'>:STRING</code>, the
1087     object's octets are converted to a string using the encoding
1088     specified by <var>string-external-format</var>, which defaults
1089     to <code class='kw'>:UTF-8</code>. See <a href="http://weitz.de/flexi-streams/#external-formats">External
1090     formats</a> in the FLEXI-STREAMS documentation for supported
1091     values for the string external format. Note that, even
1092     when <var>output</var> is <code class='kw'>:STRING</code>, the
1093     start and end arguments operate on the object's underlying octets,
1094     not the string representation in a particular encoding. It's
1095     possible to produce a subsequence of the object's octets that are
1096     not valid in the desired encoding.
1097
1098     <p>If <var>output</var> is a string or pathname, the object's
1099     octets are saved to a file identified by the string or
1100     pathname. The <var>if-exists</var> argument is passed
1101     to <code>WITH-OPEN-FILE</code> to control the behavior when the
1102     output file already exists. It defaults
1103     to <code class='kw'>:SUPERSEDE</code>.
1104
1105     <p>If <var>output</var> is <code class='kw'>:STREAM</code>, a
1106     stream is returned from which the object's contents may be read.
1107
1108     <p><var>start</var> marks the first index fetched from the
1109     object's data. <var>end</var> specifies the index after the last
1110     octet fetched. If start is NIL, it defaults to 0. If end is nil,
1111     it defaults to the total length of the object. If
1112     both <var>start</var> and <var>end</var> are
1113     provided, <var>start</var> must be less than or equal
1114     to <var>end</var>.
1115
1116     <p><var>when-modified-since</var>
1117     and <var>unless-modified-since</var> are optional. If
1118     <var>when-modified-since</var> is provided, the result will be the normal
1119     object value if the object has been modified since the provided
1120     universal time, NIL otherwise. The logic is reversed for
1121     <var>unless-modified-since</var>.
1122
1123     <p><var>when-etag-matches</var> and <var>unless-etag-matches</var> are optional. If
1124     <var>when-etag-matches</var> is provided, the result will be the
1125     normal object value if the object's etag matches the provided
1126     string, NIL otherwise. The logic is reversed
1127     for <var>unless-etag-matches</var>.
1128
1129   </blockquote>
1130 </div>
1131
1132 <div class='item'>
1133   <div class='type'><a name='get-vector'>[Function]</a></div>
1134   <div class='signature'>
1135     <code class='name'>get-vector</code>
1136     <span class='args'>
1137       <var>bucket</var> <var>key</var>
1138       <code class='llkw'>&amp;key</code>
1139       <var>start</var> <var>end</var>
1140       <var>when-modified-since</var> <var>unless-modified-since</var>
1141       <var>when-etag-matches</var> <var>unless-etag-matches</var>
1142       <var>credentials</var>
1143     </span>
1144     <span class='result'>=> <var>vector</var></span>
1145   </div>
1146
1147   <blockquote class='description'>
1148     <p>get-vector is a convenience interface to <a href='#get-object'><tt>GET-OBJECT</tt></a>. It is equivalent
1149       to calling:
1150
1151 <pre class='code'>
1152   (get-object bucket key <b>:output :vector</b> ...)
1153 </pre>
1154   </blockquote>
1155 </div>
1156
1157 <div class='item'>
1158   <div class='type'><a name='get-string'>[Function]</a></div>
1159   <div class='signature'>
1160     <code class='name'>get-string</code>
1161     <span class='args'>
1162       <var>bucket</var> <var>key</var>
1163       <code class='llkw'>&amp;key</code>
1164       <var>external-format</var>
1165       <var>start</var> <var>end</var>
1166       <var>when-modified-since</var>
1167       <var>unless-modified-since</var>
1168       <var>when-etag-matches</var>
1169       <var>unless-etag-matches</var>
1170       <var>credentials</var>
1171     </span>
1172     <span class='result'>=> <var>string</var></span>
1173   </div>
1174
1175   <blockquote class='description'>
1176     get-string is a convenience interface
1177     to <a href='#get-object'><tt>GET-OBJECT</tt></a>. It is equivalent
1178     to calling:
1179
1180 <pre class='code'>
1181   (get-object bucket key <b>:output :string</b> :string-external-format external-format ...)
1182 </pre>
1183
1184   </blockquote>
1185 </div>
1186
1187 <div class='item'>
1188   <div class='type'><a name='get-file'>[Function]</a></div>
1189   <div class='signature'>
1190     <code class='name'>get-file</code>
1191     <span class='args'>
1192       <var>bucket</var> <var>key</var> <var>file</var>
1193       <code class='llkw'>&amp;key</code>
1194       <var>start</var> <var>end</var>
1195       <var>when-modified-since</var>
1196       <var>unless-modified-since</var>
1197       <var>when-etag-matches</var>
1198       <var>unless-etag-matches</var>
1199       <var>credentials</var>
1200     </span>
1201     <span class='result'>=> <var>pathname</var></span>
1202   </div>
1203
1204   <blockquote class='description'>
1205     <p>get-file is a convenience interface
1206       to <a href='#get-object'><tt>GET-OBJECT</tt></a>. It is
1207       equivalent to calling:
1208
1209 <pre class='code'>
1210   (get-object bucket key <b>:output file</b> ...)
1211 </pre>
1212
1213   </blockquote>
1214 </div>
1215
1216
1217 <div class='item'>
1218   <div class='type'><a name='put-object'>[Function]</a></div>
1219   <div class='signature'>
1220     <code class='name'>put-object</code>
1221     <span class='args'>
1222       <var>object</var> <var>bucket</var> <var>key</var>
1223       <code class='llkw'>&amp;key</code>
1224       <var>access-policy</var>
1225       <var>public</var>
1226       <var>metadata</var>
1227       <var>string-external-format</var>
1228       <var>cache-control</var>
1229       <var>content-encoding</var>
1230       <var>content-disposition</var>
1231       <var>content-type</var>
1232       <var>expires</var>
1233       <var>storage-class</var>
1234       <var>credentials</var>
1235     </span>
1236     <span class='result'>=> |</span>
1237   </div>
1238
1239   <blockquote class='description'>
1240     <p>Stores the octets of <var>object</var> in the location
1241     identified by <var>bucket</var> and <var>key</var>.
1242
1243     <p>If <i>object</i> is an octet vector, it is stored directly.
1244
1245     <p>If <i>object</i> is a string, it is converted to an octet
1246     vector using <i>string-external-format</i>, which defaults
1247     to <code class='kw'>:UTF-8</code>, then
1248     stored. See <a href="http://weitz.de/flexi-streams/#external-formats">External
1249     formats</a> in the FLEXI-STREAMS documentation for supported
1250     values for the string external format.
1251
1252     <p>If <i>object</i> is a pathname, its contents are loaded in
1253     memory as an octet vector and stored.
1254
1255     <p>If provided, <var>access-policy</var> should be one of the
1256     following:
1257
1258       <ul>
1259         <li> <code class='kw'>:PRIVATE</code> - object owner is
1260           granted <code class='kw'>:FULL-CONTROL</code>; this is the
1261           default behavior if no access policy is provided
1262         <li> <code class='kw'>:PUBLIC-READ</code> - all users,
1263           regardless of authentication, can read the object
1264         <li> <code class='kw'>:AUTHENTICATED-READ</code> -
1265           authenticated Amazon AWS users can read the object
1266       </ul>
1267
1268     <p>For more information about access policies,
1269       see <a href='http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTAccessPolicy.html'>Canned
1270         Access Policies</a> in the Amazon S3 developer documentation.
1271
1272     <p>If <var>public</var> is <i>true</i>, it has the same effect as
1273       providing an <var>access-policy</var>
1274       of <code class='kw'>:PUBLIC-READ</code>. An error is signaled if
1275       both <var>public</var> and
1276       <var>access-policy</var> are provided.
1277
1278
1279     <p>If provided, <var>metadata</var> should be an alist of Amazon
1280     metadata to set on the object. When the object is fetched again,
1281     the metadata will be returned in HTTP headers prefixed with
1282     "x-amz-meta-".
1283
1284     <p>The <i>cache-control</i>, <i>content-encoding</i>, <i>content-disposition</i>,
1285     <i>content-type</i>, and <i>expires</i> values are all used to set
1286     HTTP properties of the object that are returned with subsequent
1287     GET or HEAD requests. If <i>content-type</i> is not set, it
1288     defaults to "binary/octet-stream". The others default to
1289     NIL. If <i>expires</i> is provided, it should be a universal time.
1290
1291     <p>If provided, <var>storage-class</var> should refer to one of
1292     the standard storage classes available for S3; currently the
1293     accepted values are the strings "STANDARD" and
1294     "REDUCED_REDUNDANCY". Using other values may trigger an API error
1295     from S3. For more information about reduced redundancy storage,
1296     see <a href="http://docs.amazonwebservices.com/AmazonS3/latest/dev/Introduction.html#RRS">Reduced
1297     Redundancy Storage</a> in the Developer Guide.
1298 </div>
1299
1300 <div class='item'>
1301   <div class='type'><a name='put-vector'>[Function]</a></div>
1302   <div class='signature'>
1303     <code class='name'>put-vector</code>
1304     <span class='args'>
1305       <var>vector</var>
1306       <var>bucket</var>
1307       <var>key</var> <code class='llkw'>&amp;key</code>
1308       <var>start</var> <var>end</var>
1309       <var>access-policy</var>
1310       <var>public</var> <var>metadata</var>
1311       <var>content-disposition</var>
1312       <var>content-encoding</var>
1313       <var>content-type</var>
1314       <var>expires</var>
1315       <var>storage-class</var>
1316       <var>credentials</var>
1317     </span>
1318     <span class='result'>=> |</span>
1319   </div>
1320
1321   <blockquote class='description'>
1322     <p>put-vector is a convenience interface
1323     to <a href='#put-object'><tt>PUT-OBJECT</tt></a>. It is similar
1324     to calling:
1325
1326 <pre class='code'>
1327   (put-object vector bucket key ...)
1328 </pre>
1329   </blockquote>
1330
1331   <p>If one of <var>start</var> or <var>end</var> is provided, they
1332     are used as bounding index designators on the string, and only a
1333     subsequence is used.
1334 </div>
1335
1336 <div class='item'>
1337   <div class='type'><a name='put-string'>[Function]</a></div>
1338   <div class='signature'>
1339     <code class='name'>put-string</code>
1340     <span class='args'>
1341       <var>string</var> <var>bucket</var> <var>key</var>
1342       <code class='llkw'>&amp;key</code>
1343       <var>start</var> <var>end</var>
1344       <var>external-format</var>
1345       <var>access-policy</var>
1346       <var>public</var> <var>metadata</var>
1347       <var>content-disposition</var>
1348       <var>content-encoding</var>
1349       <var>content-type</var>
1350       <var>expires</var>
1351       <var>storage-class</var>
1352       <var>credentials</var>
1353     </span>
1354     <span class='result'>=> |</span>
1355   </div>
1356
1357   <blockquote class='description'>
1358     <p>put-string is a convenience interface
1359 to <a href='#put-object'><tt>PUT-OBJECT</tt></a>. It is similar to
1360 calling:
1361
1362 <pre class='code'>
1363   (put-object string bucket key :string-external-format external-format ...)
1364 </pre>
1365   </blockquote>
1366
1367   <p>If one of <var>start</var> or end is <var>supplied</var>, they
1368     are used as bounding index designators on the string, and only a
1369     substring is used.
1370 </div>
1371
1372 <div class='item'>
1373   <div class='type'><a name='put-file'>[Function]</a></div>
1374   <div class='signature'>
1375     <code class='name'>put-file</code>
1376     <span class='args'>
1377       <var>file</var> <var>bucket</var> <var>key</var>
1378       <code class='llkw'>&amp;key</code>
1379       <var>start</var> <var>end</var>
1380       <var>access-policy</var>
1381       <var>public</var> <var>metadata</var>
1382       <var>content-disposition</var> <var>content-encoding</var> <var>content-type</var>
1383       <var>expires</var>
1384       <var>storage-class</var>
1385       <var>credentials</var>
1386     </span>
1387     <span class='result'>=> |</span>
1388   </div>
1389
1390   <blockquote class='description'>
1391     <p>put-file is a convenience interface
1392     to <a href='#put-object'><tt>PUT-OBJECT</tt></a>. It is almost
1393     equivalent to calling:
1394
1395 <pre class='code'>
1396   (put-object (pathname file) bucket key ...)
1397 </pre>
1398
1399     <p>If <var>key</var> is T, the <code>FILE-NAMESTRING</code> of
1400       the file is used as the key instead of <i>key</i>.
1401
1402     <p>If one of <var>start</var> or <var>end</var> is supplied, only
1403       a subset of the file is used. If <var>start</var> is not
1404       NIL, <var>start</var> octets starting from the beginning of the
1405       file are skipped. If <var>end</var> is not NIL, octets in the
1406       file at and after <var>end</var> are ignored. An error of type
1407       <tt>CL:END-OF-FILE</tt> is signaled if <var>end</var> is
1408       provided and the file size is less than <var>end</var>.
1409   </blockquote>
1410 </div>
1411
1412
1413 <div class='item'>
1414   <div class='type'><a name='put-stream'>[Function]</a></div>
1415   <div class='signature'>
1416     <code class='name'>put-stream</code>
1417     <span class='args'>
1418       <var>file</var> <var>bucket</var> <var>key</var>
1419       <code class='llkw'>&amp;key</code>
1420       <var>start</var> <var>end</var>
1421       <var>access-policy</var>
1422       <var>public</var> <var>metadata</var>
1423       <var>content-disposition</var> <var>content-encoding</var> <var>content-type</var>
1424       <var>expires</var>
1425       <var>storage-class</var>
1426       <var>credentials</var>
1427     </span>
1428     <span class='result'>=> |</span>
1429   </div>
1430
1431   <blockquote class='description'>
1432     <p>put-stream is similar to
1433     to <a href='#put-object'><tt>PUT-OBJECT</tt></a>. It has the same
1434     effect as collecting octets from <var>stream</var> into a vector
1435     and using:
1436
1437 <pre class='code'>
1438   (put-object vector bucket key ...)
1439 </pre>
1440
1441     <p>If <var>start</var> is not NIL, <var>start</var> octets
1442       starting from the current position in the stream are skipped
1443       before collecting.
1444
1445     <p>If <var>end</var> is NIL, octets are collected until the end of
1446       the stream is reached.
1447
1448     <p>If <var>end</var> is not NIL, collecting octets stops just
1449       before reaching <var>end</var> in the stream. An error of type
1450       <tt>CL:END-OF-FILE</tt> is signaled if the stream ends
1451       prematurely.
1452   </blockquote>
1453 </div>
1454
1455
1456 <div class='item'>
1457   <div class='type'><a name='copy-object'>[Function]</a></div>
1458   <div class='signature'>
1459     <code class='name'>copy-object</code>
1460     <span class='args'>
1461       <code class='llkw'>&amp;key</code>
1462       <var>from-bucket</var>
1463       <var>from-key</var>
1464       <var>to-bucket</var>
1465       <var>to-key</var> <br>
1466       <var>access-policy</var>
1467       <var>public</var> <br>
1468       <var>when-etag-matches</var>
1469       <var>unless-etag-matches</var> <br>
1470       <var>when-modified-since</var>
1471       <var>unless-modified-since</var> <br>
1472       <var>metadata</var> <var>public</var> <var>precondition-errors</var>
1473       <var>storage-class</var>
1474       <var>credentials</var>
1475     </span>
1476     <span class='result'>=> |</span>
1477   </div>
1478
1479   <blockquote class='description'>
1480     <p>Copies the object identified by <var>from-bucket</var>
1481     and <var>from-key</var> to a new location identified by
1482     <var>to-bucket</var> and <var>to-key</var>.
1483
1484     If <var>to-bucket</var> is NIL, <var>from-bucket</var> is used as
1485     the target. If <var>to-key</var> is nil, <var>from-key</var> is
1486     used as the target. An error is signaled if both <var>to-bucket</var> and
1487     <var>to-key</var> are NIL.
1488
1489     <p><var>access-policy</var> and <var>public</var> have the same
1490       effect on the target object as
1491       in <a href='#put-object'><tt>PUT-OBJECT</tt></a>.
1492
1493     <p>The precondition arguments <var>when-etag-matches</var>, <var>unless-etag-matches</var>,
1494     <var>when-modified-since</var>, and <var>unless-modified-since</var> work the same way they
1495     do in <a href='#get-object'><tt>GET-OBJECT</tt></a>, but with one difference: if <var>precondition-errors</var> is
1496     <i>true</i>, an <code>PRECONDITION-FAILED</code> error is signaled
1497     when a precondition does not hold, instead of returning NIL.
1498
1499     <p>If <var>metadata</var> is explicitly provided, it follows the
1500     same behavior as
1501     with <a href='#put-object'><tt>PUT-OBJECT</tt></a>. Passing NIL
1502     means that the new object has no metadata. Otherwise, the metadata
1503     is copied from the original object.
1504
1505     <p>If <var>storage-class</var> is provided, it should refer to one
1506     of the standard storage classes available for S3; currently the
1507     accepted values are the strings "STANDARD" and
1508     "REDUCED_REDUNDANCY". Using other values may trigger an API error
1509     from S3. For more information about reduced redundancy storage,
1510     see <a href="http://docs.amazonwebservices.com/AmazonS3/latest/dev/Introduction.html#RRS">Reduced
1511     Redundancy Storage</a> in the Developer Guide.
1512   </blockquote>
1513 </div>
1514
1515 <div class='item'>
1516   <div class='type'><a name='delete-object'>[Function]</a></div>
1517   <div class='signature'>
1518     <code class='name'>delete-object</code>
1519     <span class='args'>
1520       <var>bucket</var>
1521       <var>key</var>
1522       <code class='llkw'>&amp;key</code>
1523       <var>credentials</var>
1524     </span>
1525     <span class='result'>=> |</span>
1526   </div>
1527
1528   <blockquote class='description'>
1529     <p>Deletes the object identified by <var>bucket</var>
1530       and <var>key</var>.
1531     <p>If <var>bucket</var> is a valid bucket for
1532       which you have delete access granted, S3 will always return a success
1533       response, even if <var>key</var> does not reference an existing
1534       object.
1535   </blockquote>
1536 </div>
1537
1538 <div class='item'>
1539   <div class='type'><a name='delete-objects'>[Function]</a></div>
1540   <div class='signature'>
1541     <code class='name'>delete-objects</code>
1542     <span class='args'>
1543       <var>bucket</var>
1544       <var>keys</var>
1545       <code class='llkw'>&amp;key</code>
1546       <var>credentials</var>
1547     </span>
1548     <span class='result'>=> <var>deleted-count</var>, <var>errors</var></span>
1549   </div>
1550
1551   <blockquote class='description'>
1552     <p>Deletes <var>keys</var>, which should be a sequence of keys,
1553     from <var>bucket</var>. The primary value is the number of objects
1554     deleted. The secondary value is a list of error plists; if there
1555     are no errors deleting any of the keys, the secondary value is
1556     NIL.
1557   </blockquote>
1558 </div>
1559
1560 <div class='item'>
1561   <div class='type'><a name='delete-all-objects'>[Function]</a></div>
1562   <div class='signature'>
1563     <code class='name'>delete-all-objects</code>
1564     <span class='args'>
1565       <var>bucket</var>
1566       <code class='llkw'>&amp;key</code>
1567       <var>credentials</var>
1568     </span>
1569     <span class='result'>=> <var>count</var></span>
1570   </div>
1571
1572   <blockquote class='description'>
1573     <p>Deletes all objects in <var>bucket</var> and returns the count
1574       of objects deleted.
1575   </blockquote>
1576 </div>
1577
1578
1579 <div class='item'>
1580   <div class='type'><a name='object-metadata'>[Function]</a></div>
1581   <div class='signature'>
1582     <code class='name'>object-metadata</code>
1583     <span class='args'>
1584       <var>bucket</var>
1585       <var>key</var>
1586       <code class='llkw'>&amp;key</code>
1587       <var>credentials</var>
1588     </span>
1589     <span class='result'>=> <var>metadata-alist</var></span>
1590   </div>
1591
1592   <blockquote class='description'>
1593     <p>Returns the metadata for the object identified by <var>bucket</var> and <var>key</var>, or
1594     NIL if there is no metadata. For example:
1595
1596 <pre class='code'>
1597   * <b>(put-string "Hadjaha!" "zs3-demo" "hadjaha.txt" :metadata (parameters-alist :language "Swedish"))</b>
1598   => #&lt;RESPONSE 200 "OK" {1003BD2841}>
1599
1600   * <b>(object-metadata "zs3-demo" "hadjaha.txt")</b>
1601   => ((:LANGUAGE . "Swedish"))
1602 </pre>
1603
1604   </blockquote>
1605 </div>
1606
1607 <div class='item'>
1608   <div class='type'><a name='set-storage-class'>[Function]</a></div>
1609   <div class='signature'>
1610     <code class='name'>set-storage-class</code>
1611     <span class='args'>
1612       <var>bucket</var>
1613       <var>key</var>
1614       <var>storage-class</var>
1615       <code class='llkw'>&amp;key</code>
1616       <var>credentials</var>
1617     </span>
1618     <span class='result'>=> |</span>
1619   </div>
1620
1621   <blockquote class='description'>
1622     <p>Sets the storage class of the object identified
1623       by <var>bucket</var> and <var>key</var>
1624       to <var>storage-class</var>. This is a convenience function that
1625       uses <a href='#copy-object'><tt>COPY-OBJECT</tt></a> to make
1626       storage class changes.
1627
1628     <p>The storage class of an object can be determined by querying
1629       the bucket with <a href='#all-keys'><tt>ALL-KEYS</tt></a>
1630       or <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> and
1631       using <a href='#storage-class'><tt>STORAGE-CLASS</tt></a> on one
1632       of the resulting key objects.
1633   </blockquote>
1634 </div>
1635
1636
1637
1638 <a name='access-control'><h3>Access Control</h3></a>
1639
1640 <p>Each S3 resource has an associated access control list that is
1641   created automatically when the resource is created. The access
1642   control list specifies the resource owner and a list of permission
1643   grants.
1644
1645 <p>Grants consist of a permission and a grantee. The permission must
1646   be one of <code class='kw'>:READ</code>, <code class='kw'>:WRITE</code>,
1647   <code class='kw'>:READ-ACL</code>, <code class='kw'>:WRITE-ACL</code>,
1648   or <code class='kw'>:FULL-CONTROL</code>. The grantee should be a
1649   person object, an acl-group object, or an acl-email object.
1650
1651 <p>ZS3 has several functions that assist in reading, modifying, and
1652   storing access control lists.
1653
1654
1655 <div class='item'>
1656   <div class='type'><a name='get-acl'>[Function]</a></div>
1657   <div class='signature'>
1658     <code class='name'>get-acl</code>
1659     <span class='args'>
1660       <code class='llkw'>&amp;key</code>
1661       <var>bucket</var>
1662       <var>key</var>
1663       <var>credentials</var>
1664     </span>
1665     <span class='result'>=> <var>owner</var>, <var>grants</var></span>
1666   </div>
1667
1668   <blockquote class='description'>
1669     <p>Returns the owner and grant list for a resource as
1670     multiple values.
1671   </blockquote>
1672 </div>
1673
1674
1675 <div class='item'>
1676   <div class='type'><a name='put-acl'>[Function]</a></div>
1677   <div class='signature'>
1678     <code class='name'>put-acl</code>
1679     <span class='args'>
1680       <var>owner</var> <var>grants</var>
1681       <code class='llkw'>&amp;key</code>
1682       <var>bucket</var>
1683       <var>key</var>
1684       <var>credentials</var>
1685     </span>
1686     <span class='result'>=> |</span>
1687   </div>
1688
1689   <blockquote class='description'>
1690     <p>Sets the owner and grant list of a resource.
1691   </blockquote>
1692 </div>
1693
1694
1695 <div class='item'>
1696   <div class='type'><a name='grant'>[Function]</a></div>
1697   <div class='signature'>
1698     <code class='name'>grant</code>
1699     <span class='args'>
1700       <var>permission</var>
1701       <code class='llkw'>&amp;key</code>
1702       <var>to</var>
1703     </span>
1704     <span class='result'>=> <var>grant</var></span>
1705   </div>
1706
1707   <blockquote class='description'>
1708     <p>Returns a grant object that represents a permission (one of <code class='kw'>:READ</code>, <code class='kw'>:WRITE</code>,
1709       <code class='kw'>:READ-ACL</code>, <code class='kw'>:WRITE-ACL</code>,
1710       or <code class='kw'>:FULL-CONTROL</code>) for the
1711       grantee <var>to</var>. For example:
1712
1713 <pre class='code'>
1714   * <b>(grant :full-control :to (<a href='#acl-email'>acl-email</a> "bob@example.com"))</b>
1715   => #&lt;GRANT :FULL-CONTROL to "bob@example.com">
1716
1717   * <b>(grant :read :to <a href='#*all-users*'>*all-users*</a>)</b>
1718   => #&lt;GRANT :READ to "AllUsers">
1719 </pre>
1720
1721     <p>It can be used to create or modify a grant list for use
1722     with <a href='#put-acl'><tt>PUT-ACL</tt></a>.
1723   </blockquote>
1724 </div>
1725
1726
1727 <div class='item'>
1728   <div class='type'><a name='acl-eqv'>[Function]</a></div>
1729   <div class='signature'>
1730     <code class='name'>acl-eqv</code>
1731     <span class='args'>
1732       <var>a</var> <var>b</var>
1733     </span>
1734     <span class='result'>=> <var>boolean</var></span>
1735   </div>
1736
1737   <blockquote class='description'>
1738     <p>Returns <i>true</i> if <var>a</var> and <var>b</var> are equivalent
1739       ACL-related objects (person, group, email, or grant).
1740   </blockquote>
1741 </div>
1742
1743
1744 <div class='item'>
1745   <div class='type'><a name='*all-users*'>[Special variable]</a></div>
1746   <div class='signature'>
1747     <code class='name'>*all-users*</code>
1748   </div>
1749
1750   <blockquote class='description'>
1751     <p>This acl-group includes all users, including unauthenticated
1752     clients.
1753   </blockquote>
1754 </div>
1755
1756
1757 <div class='item'>
1758   <div class='type'><a name='*aws-users*'>[Special variable]</a></div>
1759   <div class='signature'>
1760     <code class='name'>*aws-users*</code>
1761   </div>
1762
1763   <blockquote class='description'>
1764     <p>This acl-group object includes only users that have an
1765     Amazon Web Services account.
1766   </blockquote>
1767 </div>
1768
1769
1770 <div class='item'>
1771   <div class='type'><a name='*log-delivery*'>[Special variable]</a></div>
1772   <div class='signature'>
1773     <code class='name'>*log-delivery*</code>
1774   </div>
1775
1776   <blockquote class='description'>
1777     <p>This acl-group object includes the S3 system user that creates
1778       logfile objects. See
1779       also <a href='#enable-logging-to'><tt>ENABLE-LOGGING-TO</tt></a>.
1780   </blockquote>
1781 </div>
1782
1783
1784 <div class='item'>
1785   <div class='type'><a name='acl-email'>[Function]</a></div>
1786   <div class='signature'>
1787     <code class='name'>acl-email</code>
1788     <span class='args'>
1789       <var>email-address</var>
1790     </span>
1791     <span class='result'>=> <var>acl-email</var></span>
1792   </div>
1793
1794   <blockquote class='description'>
1795     <p>Returns an acl-email object, which can be used as a grantee for
1796       <a href='#grant'><tt>GRANT</tt></a>.
1797   </blockquote>
1798 </div>
1799
1800
1801 <div class='item'>
1802   <div class='type'><a name='acl-person'>[Function]</a></div>
1803   <div class='signature'>
1804     <code class='name'>acl-person</code>
1805     <span class='args'>
1806       <var>id</var>
1807       <code class='llkw'>&amp;optional</code>
1808       <var>display-name</var>
1809     </span>
1810     <span class='result'>=> <var>acl-person</var></span>
1811   </div>
1812
1813   <blockquote class='description'>
1814     <p>Returns an acl-person object for use as a resource owner (for
1815       <a href='#put-acl'><tt>PUT-ACL</tt></a>) or as a grantee
1816       (for <a href='#grant'><tt>GRANT</tt></a>). <var>id</var> must be
1817       a string representing the person's Amazon AWS canonical ID; for
1818       information about getting the canonical ID, see
1819       the <a href="http://docs.amazonwebservices.com/AmazonS3/2006-03-01/S3_ACLs.html">Access
1820       Control Lists</a> in the Amazon S3 developer
1821       documentation. If <var>display-name</var> is provided, it is
1822       used only for printing the object in Lisp; it is ignored when
1823       passed to S3.
1824   </blockquote>
1825 </div>
1826
1827
1828 <div class='item'>
1829   <div class='type'><a name='me'>[Function]</a></div>
1830   <div class='signature'>
1831     <code class='name'>me</code>
1832     <span class='args'>
1833       <code class='llkw'>&amp;key</code>
1834       <var>credentials</var>
1835     </span>
1836     <span class='result'>=> <var>acl-person</var></span>
1837   </div>
1838
1839   <blockquote class='description'>
1840     <p>Returns the acl-person object associated with the current
1841       credentials.
1842
1843     <p>This data requires a S3 request, but the result is always the
1844     same per credentials and is cached.
1845   </blockquote>
1846 </div>
1847
1848
1849 <div class='item'>
1850   <div class='type'><a name='make-public'>[Function]</a></div>
1851   <div class='signature'>
1852     <code class='name'>make-public</code>
1853     <span class='args'>
1854       <code class='llkw'>&amp;key</code>
1855       <var>bucket</var>
1856       <var>key</var>
1857       <var>credentials</var>
1858     </span>
1859     <span class='result'>=> |</span>
1860   </div>
1861
1862   <blockquote class='description'>
1863     <p>Makes a resource publicly accessible, i.e. readable by
1864       the <a href='#*all-users*'><tt>*ALL-USERS*</tt></a> group.
1865   </blockquote>
1866 </div>
1867
1868
1869 <div class='item'>
1870   <div class='type'><a name='make-private'>[Function]</a></div>
1871   <div class='signature'>
1872     <code class='name'>make-private</code>
1873     <span class='args'>
1874       <code class='llkw'>&amp;key</code>
1875       <var>bucket</var>
1876       <var>key</var>
1877       <var>credentials</var>
1878     </span>
1879     <span class='result'>=> |</span>
1880   </div>
1881
1882   <blockquote class='description'>
1883     <p>Removes public access to a resource, i.e. removes all
1884       access grants for
1885       the <a href='#*all-users*'><tt>*ALL-USERS*</tt></a> group.
1886   </blockquote>
1887 </div>
1888
1889
1890
1891 <a name='access-logging'><h3>Access Logging</h3></a>
1892
1893 <p>S3 offers support for logging information about client
1894   requests. Logfile objects are delivered by a system user in
1895   the <a href='#*log-delivery*'><tt>*LOG-DELIVERY*</tt></a> group to a
1896   bucket of your choosing. For more information about S3 access
1897   logging and the logfile format, see
1898   the <a href="http://docs.amazonwebservices.com/AmazonS3/2006-03-01/ServerLogs.html">Server
1899   Access Logging</a> in the Amazon S3
1900   developer documentation.
1901
1902 <div class='item'>
1903   <div class='type'><a name='enable-logging-to'>[Function]</a></div>
1904   <div class='signature'>
1905     <code class='name'>enable-logging-to</code>
1906     <span class='args'>
1907       <var>bucket</var>
1908       <code class='llkw'>&amp;key</code>
1909       <var>credentials</var>
1910     </span>
1911     <span class='result'>=> |</span>
1912   </div>
1913
1914   <blockquote class='description'>
1915     Adds the necessary permission grants to <var>bucket</var> to allow
1916     S3 to write logfile objects into it.
1917   </blockquote>
1918 </div>
1919
1920
1921 <div class='item'>
1922   <div class='type'><a name='disable-logging-to'>[Function]</a></div>
1923   <div class='signature'>
1924     <code class='name'>disable-logging-to</code>
1925     <span class='args'>
1926       <var>bucket</var>
1927       <code class='llkw'>&amp;key</code>
1928       <var>credentials</var>
1929     </span>
1930     <span class='result'>=> |</span>
1931   </div>
1932
1933   <blockquote class='description'>
1934     <p>Changes the access control list of <var>bucket</var> to remove
1935     all grants for
1936     the <a href='#*log-delivery*'><tt>*LOG-DELIVERY*</tt></a> group.
1937   </blockquote>
1938 </div>
1939
1940
1941 <div class='item'>
1942   <div class='type'><a name='enable-logging'>[Function]</a></div>
1943   <div class='signature'>
1944     <code class='name'>enable-logging</code>
1945     <span class='args'>
1946       <var>bucket</var>
1947       <var>target-bucket</var>
1948       <var>target-prefix</var>
1949       <code class='llkw'>&amp;key</code>
1950       <var>target-grants</var>
1951       <var>credentials</var>
1952     </span>
1953     <span class='result'>=> |</span>
1954   </div>
1955
1956   <blockquote class='description'>
1957     <p>Enables logging of all requests
1958     involving <var>bucket</var>. Logfile objects are created in
1959       <var>target-bucket</var> and each logfile's key starts with
1960       <var>target-prefix</var>.
1961
1962     <p>When a new logfile is
1963       created, its list of access control grants is extended with
1964       <var>target-grants</var>, if any.
1965
1966     <p>If <var>target-bucket</var> does not have the necessary grants
1967     to allow logging, the grants are implicitly added by
1968     calling <a href='#enable-logging-to'><tt>ENABLE-LOGGING-TO</tt></a>.
1969   </blockquote>
1970 </div>
1971
1972
1973 <div class='item'>
1974   <div class='type'><a name='disable-logging'>[Function]</a></div>
1975   <div class='signature'>
1976     <code class='name'>disable-logging</code>
1977     <span class='args'>
1978       <var>bucket</var> <code class='llkw'>&amp;key</code> <var>credentials</var>
1979     </span>
1980     <span class='result'>=> |</span>
1981   </div>
1982
1983   <blockquote class='description'>
1984     Disables logging for <var>bucket</var>.
1985   </blockquote>
1986 </div>
1987
1988
1989 <div class='item'>
1990   <div class='type'><a name='logging-setup'>[Function]</a></div>
1991   <div class='signature'>
1992     <code class='name'>logging-setup</code>
1993     <span class='args'>
1994       <var>bucket</var>
1995       <code class='llkw'>&amp;key</code>
1996       <var>credentials</var>
1997     </span>
1998     <span class='result'>=> <var>target-bucket</var>,
1999       <var>target-prefix</var>,
2000       <var>target-grants</var></span>
2001   </div>
2002
2003   <blockquote class='description'>
2004     <p>If logging is enabled for <var>bucket</var>, returns the target
2005       bucket, target prefix, and target grants as multiple values.
2006   </blockquote>
2007 </div>
2008
2009
2010 <a name='misc'><h3>Miscellaneous Operations</h3></a>
2011
2012 <p>
2013
2014 <div class='item'>
2015   <div class='type'><a name='*use-ssl*'>[Special variable]</a></div>
2016   <div class='signature'>
2017     <code class='name'>*use-ssl*</code>
2018   </div>
2019
2020   <blockquote class='description'>
2021     <p>When <i>true</i>, requests to S3 are sent via HTTPS. The
2022       default is NIL.
2023   </blockquote>
2024 </div>
2025
2026
2027 <div class='item'>
2028   <div class='type'><a name='make-post-policy'>[Function]</a></div>
2029   <div class='signature'>
2030     <code class='name'>make-post-policy</code>
2031     <span class='args'>
2032       <code class='llkw'>&amp;key</code>
2033       <var>expires</var>
2034       <var>conditions</var>
2035       <var>credentials</var>
2036     </span>
2037     <span class='result'>=> <var>policy</var>, <var>signature</var></span>
2038   </div>
2039
2040   <blockquote class='description'>
2041     <p>Returns an encoded HTML POST form policy and its signature as
2042     multiple values. The policy can be used to conditionally allow any
2043     user to put objects into S3.
2044
2045     <p><var>expires</var> must be a universal time after which
2046     the policy is no longer accepted.
2047
2048     <p><var>conditions</var> must be a list of conditions that the
2049     posted form fields must satisfy. Each condition is a list of a
2050     condition keyword, a form field name, and the form field
2051     value. For example, the following are all valid conditions:
2052
2053     <p>
2054       <ul>
2055         <li> <code>(:starts-with "key" "uploads/")</code>
2056         <li> <code>(:eq "bucket" "user-uploads")</code>
2057         <li> <code>(:eq "acl" "public-read")</code>
2058         <li> <code>(:range "content-length-range" 1 10000)</code>
2059       </ul>
2060
2061     <p>These conditions are converted into a post policy description,
2062     base64-encoded, and returned as <var>policy</var>. The signature
2063     is returned as <var>signature</var>. These values can then be
2064     embedded in an HTML form and used to allow direct browser uploads.
2065
2066     <p>For example, if <var>policy</var> is
2067     "YSBwYXRlbnRseSBmYWtlIHBvbGljeQ==" and the policy signature is
2068     "ZmFrZSBzaWduYXR1cmU=", you could construct a form like this:
2069
2070 <p class='html'>
2071 &lt;form action="http://user-uploads.s3.amazonaws.com/" method="post" enctype="multipart/form-data"><br>
2072 &lt;input type="input" name="key" value="uploads/fun.jpg"><br>
2073 &lt;input type=hidden name="acl" value="public-read"><br>
2074 &lt;input type=hidden name="AWSAccessKeyId" value="8675309JGT9876430310"><br>
2075 &lt;input type=hidden name="Policy" value="YSBwYXRlbnRseSBmYWtlIHBvbGljeQ=="><br>
2076 &lt;input type=hidden name='Signature' value="ZmFrZSBzaWduYXR1cmU="><br>
2077 &lt;input name='file' type='file'><br>
2078 &lt;input type=submit value='Submit'><br>
2079 &lt;/form><br>
2080
2081    <p>For full, detailed documentation of browser-based POST uploads
2082    and policy documents,
2083    see <a href="http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingHTTPPOST.html">Browser-Based
2084    Uploads Using POST</a> in the Amazon S3 developer documentation.
2085   </blockquote>
2086 </div>
2087
2088
2089 <div class='item'>
2090   <div class='type'><a name='head'>[Function]</a></div>
2091   <div class='signature'>
2092     <code class='name'>head</code>
2093     <span class='args'>
2094       <code class='llkw'>&amp;key</code>
2095       <var>bucket</var>
2096       <var>key</var>
2097       <var>parameters</var>
2098       <var>credentials</var>
2099     </span>
2100     <span class='result'>=> <var>headers-alist</var>,
2101       <var>status-code</var>,
2102       <var>phrase</var></span>
2103   </div>
2104
2105   <blockquote class='description'>
2106     <p>Submits a HTTP HEAD request for the resource identified by
2107       <var>bucket</var> and optionally <var>key</var>. Returns the
2108       <a href='http://weitz.de/drakma/'>Drakma</a> headers, HTTP
2109       status code, and HTTP phrase as multiple values.
2110
2111     <p>When <var>parameters</var> is supplied, it should be an alist
2112       of keys and values to pass as GET request parameters. For
2113       example:
2114
2115 <pre class='code'>
2116   * <b>(head :bucket "zs3-demo" :parameters (<a href='http://cliki.net/parameters-alist?download'>parameters-alist</a> :max-keys 0))</b>
2117   => ((:X-AMZ-ID-2  . "...")
2118       (:X-AMZ-REQUEST-ID . "...")
2119       (:DATE . "Sat, 27 Sep 2008 19:00:35 GMT")
2120       (:CONTENT-TYPE . "application/xml")
2121       (:TRANSFER-ENCODING . "chunked")
2122       (:SERVER . "AmazonS3")
2123       (:CONNECTION . "close")),
2124       200,
2125       "OK"</pre>
2126   </blockquote>
2127 </div>
2128
2129
2130 <div class='item'>
2131   <div class='type'><a name='authorized-url'>[Function]</a></div>
2132   <div class='signature'>
2133     <code class='name'>authorized-url</code>
2134     <span class='args'>
2135       <code class='llkw'>&amp;key</code>
2136       <var>bucket</var>
2137       <var>key</var>
2138       <var>vhost</var>
2139       <var>expires</var>
2140       <var>ssl</var>
2141       <var>sub-resource</var>
2142       <var>credentials</var>
2143     </span>
2144     <span class='result'>=> <var>url</var></span>
2145   </div>
2146
2147   <blockquote class='description'>
2148     <p>Creates an URL that allows temporary access to a resource regardless
2149     of its ACL.
2150
2151     <p>If neither <var>bucket</var> nor <var>key</var> is specified, the top-level bucket listing
2152     is accessible. If <var>key</var> is not specified, listing the keys of <var>bucket</var> is
2153     accessible. If both <var>bucket</var> and key are <var>specified</var>, the object specified
2154     by <var>bucket</var> and <var>key</var> is accessible.
2155
2156     <p><var>expires</var> is required, and should be the integer
2157     universal time after which the URL is no longer valid.
2158
2159     <p><var>vhost</var> controls the construction of the
2160     url. If <var>vhost</var> is nil, the constructed URL refers to the
2161     bucket, if present, as part of the path. If <var>vhost</var>
2162     is <code class='kw'>:AMAZON</code>, the bucket name is used as a
2163     prefix to the Amazon hostname. If <var>vhost</var>
2164     is <code class='kw'>:FULL</code>, the bucket name becomes the full
2165     hostname of the url. For example:
2166
2167 <pre class='code'>
2168   * <b>(authorized-url :bucket "foo" :key "bar" :vhost nil)</b>
2169   =&gt; "http://s3.amazonaws.com/foo/bar?..."
2170
2171   * <b>(authorized-url :bucket "foo" :key "bar" :vhost :amazon)</b>
2172   =&gt; "http://foo.s3.amazonaws.com/bar?..."
2173
2174   * <b>(authorized-url :bucket "foo.example.com" :key "bar" :vhost :full)</b>
2175   =&gt;  "http://foo.example.com/bar?..."
2176 </pre>
2177
2178     <p>If <i>ssl</i> is <i>true</i>, the URL has "https" as the scheme,
2179     otherwise it has "http".
2180
2181     <p>If <i>sub-resource</i> is specified, it is used as part of the
2182     query string to access a specific sub-resource. Example Amazon
2183     sub-resources include "acl" for access to the ACL, "location" for
2184     location information, and "logging" for logging information. For
2185     more information about the various sub-resources, see the Amazon
2186     S3 developer documentation.
2187   </blockquote>
2188 </div>
2189
2190
2191 <div class='item'>
2192   <div class='type'><a name='resource-url'>[Function]</a></div>
2193   <div class='signature'>
2194     <code class='name'>resource-url</code>
2195     <span class='args'>
2196       <code class='llkw'>&amp;key</code>
2197       <var>bucket</var>
2198       <var>key</var>
2199       <var>vhost</var>
2200       <var>ssl</var>
2201       <var>sub-resource</var>
2202     </span>
2203     <span class='result'>=> <var>url</var></span>
2204   </div>
2205
2206   <blockquote class='description'>
2207     <p>Returns an URL that can be used to reference a resource. See
2208       <a href='#authorized-url'><tt>AUTHORIZED-URL</tt></a> for more
2209       info.
2210   </blockquote>
2211 </div>
2212
2213
2214 <a name='utility'><h3>Utility Functions</h3></a>
2215
2216 <p>
2217
2218 <div class='item'>
2219   <div class='type'><a name='octet-vector'>[Function]</a></div>
2220   <div class='signature'>
2221     <code class='name'>octet-vector</code>
2222     <span class='args'>
2223       <code class='llkw'>&amp;rest</code>
2224       <var>octets</var>
2225     </span>
2226     <span class='result'>=> <var>octet-vector</var></span>
2227   </div>
2228
2229   <blockquote class='description'>
2230     <p>Returns a vector of type
2231       <code>(simple-array&nbsp;(unsigned-byte&nbsp;8)&nbsp;(*))</code> initialized with <var>octets</var>.
2232   </blockquote>
2233 </div>
2234
2235
2236 <div class='item'>
2237   <div class='type'><a name='now+'>[Function]</a></div>
2238   <div class='signature'>
2239     <code class='name'>now+</code>
2240     <span class='args'>
2241       <var>delta</var>
2242     </span>
2243     <span class='result'>=> <var>universal-time</var></span>
2244   </div>
2245
2246   <blockquote class='description'>
2247     <p>Returns a universal time that represents the current time
2248       incremented by <var>delta</var> seconds. It's useful for passing
2249       as the <code class='kw'>:EXPIRES</code> parameter to functions
2250       like <a href='#put-object'><tt>PUT-OBJECT</tt></a>
2251       and <a href='#authorized-url'><tt>AUTHORIZED-URL</tt></a>.
2252   </blockquote>
2253 </div>
2254
2255
2256 <div class='item'>
2257   <div class='type'><a name='now-'>[Function]</a></div>
2258   <div class='signature'>
2259     <code class='name'>now-</code>
2260     <span class='args'>
2261       <var>delta</var>
2262     </span>
2263     <span class='result'>=> <var>universal-time</var></span>
2264   </div>
2265
2266   <blockquote class='description'>
2267     <p>Like <a href='#now+'><tt>NOW+</tt></a>, but decrements the
2268       current time instead of incrementing it.
2269   </blockquote>
2270 </div>
2271
2272
2273 <div class='item'>
2274   <div class='type'><a name='file-etag'>[Function]</a></div>
2275   <div class='signature'>
2276     <code class='name'>file-etag</code>
2277     <span class='args'>
2278       <var>pathname</var>
2279     </span>
2280     <span class='result'>=> <var>etag</var></span>
2281   </div>
2282
2283   <blockquote class='description'>
2284     <p>Returns the etag of <var>pathname</var>. This can be useful for the
2285       conditional arguments
2286       <code class='kw'>:WHEN-ETAG-MATCHES</code> and
2287       <code class='kw'>:UNLESS-ETAG-MATCHES</code>
2288       in <a href='#get-object'><tt>GET-OBJECT</tt></a>
2289       and <a href='#copy-object'><tt>COPY-OBJECT</tt></a>.
2290   </blockquote>
2291 </div>
2292
2293
2294 <div class='item'>
2295   <div class='type'><a name='parameters-alist'>[Function]</a></div>
2296   <div class='signature'>
2297     <code class='name'>parameters-alist</code>
2298     <span class='args'>
2299       <code class='llkw'>&amp;rest</code>
2300       <var>parameters</var>
2301       <code class='llkw'>&amp;key</code>
2302       <code class='llkw'>&amp;allow-other-keys</code>
2303     </span>
2304     <span class='result'>=> <var>alist</var></span>
2305   </div>
2306
2307   <blockquote class='description'>
2308     <p>Returns an alist based on all keyword arguments passed to the
2309       function. Keywords are converted to their lowercase symbol name and
2310       values are converted to strings. For example:
2311
2312 <pre class='code'>
2313   * <b>(parameters-alist :name "Bob" :age 21)</b>
2314   => (("name" . "Bob") ("age" . "21"))
2315 </pre>
2316
2317     <p>This can be used to construct Amazon metadata alists
2318     for <a href='#put-object'><tt>PUT-OBJECT</tt></a>
2319     and <a href='#copy-object'><tt>COPY-OBJECT</tt></a>, or request
2320     parameters in <a href='#head'><tt>HEAD</tt></a>.
2321
2322   </blockquote>
2323 </div>
2324
2325
2326
2327 <div class='item'>
2328   <div class='type'><a name='clear-redirects'>[Function]</a></div>
2329   <div class='signature'>
2330     <code class='name'>clear-redirects</code>
2331     <span class='args'>
2332     </span>
2333     <span class='result'>=> |</span>
2334   </div>
2335
2336   <blockquote class='description'>
2337     <p>Clear ZS3's internal cache of redirections.
2338
2339     <p>Most ZS3 requests are submitted against the Amazon S3 endpoint
2340       "s3.amazonaws.com". Some requests, however, are permanently
2341       redirected by S3 to new endpoints. ZS3 maintains an internal cache
2342       of permanent redirects, but it's possible for that cache to get
2343       out of sync if external processes alter the bucket structure
2344
2345     <p>For example, if the bucket "eu.zs3" is created with a EU
2346       location constraint, S3 will respond to requests to that bucket
2347       with a permanent redirect to "eu.zs3.s3.amazonaws.com", and ZS3
2348       will cache that redirect information. But if the bucket is
2349       deleted and recreated by a third party, the redirect might no
2350       longer be necessary.
2351   </blockquote>
2352 </div>
2353
2354
2355 <a name='cloudfront'><h2>CloudFront</h2>
2356
2357 <p>CloudFront functions allow the creation and manipulation of
2358   distributions. In ZS3, distributions are represented by objects that
2359   reflect the state of a distributon at some point in time. It's
2360   possible for the distribution to change behind the scenes without
2361   notice, e.g. when a distribution's <a href='#status'>status</a> is
2362   updated from "InProgress" to "Deployed".
2363
2364   <p>The
2365   functions <a href='#enable'><tt>ENABLE</tt></a>, <a href='#disable'><tt>DISABLE</tt></a>, <a href='#ensure-cname'><tt>ENSURE-CNAME</tt></a>,
2366   <a href='#remove-cname'><tt>REMOVE-CNAME</tt></a>,
2367   and <a href='#set-comment'><tt>SET-COMMENT</tt></a> are designed so
2368   that regardless of the state of the distribution provided, after the
2369   function completes, the new state of the distribution will reflect
2370   the desired update. The
2371   functions <a href='#status'><tt>STATUS</tt></a>, <a href='#cnames'><tt>CNAMES</tt></a>,
2372   and
2373   <a href='#enabledp'><tt>ENABLEDP</tt></a> do not automatically
2374   refresh the object and therefore might reflect outdated
2375   information. To ensure the object has the most recent information,
2376   use <a href='#refresh'><tt>REFRESH</tt></a>. For example, to fetch
2377   the current, live status, use <tt>(status (refresh
2378   distribution))</tt>.
2379
2380
2381
2382 <div class='item'>
2383   <div class='type'><a name='all-distributions'>[Function]</a></div>
2384   <div class='signature'>
2385     <code class='name'>all-distributions</code>
2386     <span class='args'>
2387     </span>
2388     <span class='result'>=> |</span>
2389   </div>
2390
2391   <blockquote class='description'>
2392     <p>Returns a list of all distributions.
2393   </blockquote>
2394 </div>
2395
2396 <div class='item'>
2397   <div class='type'><a name='create-distribution'>[Function]</a></div>
2398   <div class='signature'>
2399     <code class='name'>create-distribution</code>
2400     <span class='args'>
2401       <var>bucket-name</var>
2402       <code class='llkw'>&amp;key</code>
2403       <var>cnames</var>
2404       <var>enabled</var>
2405       <var>comment</var>
2406     </span>
2407     <span class='result'>=> <var>distribution</var></span>
2408   </div>
2409
2410   <blockquote class='description'>
2411     Creates and returns a new distribution object that will cache
2412     objects from the bucket named
2413     by <var>bucket-name</var>.
2414
2415     <p>If <var>cnames</var> is provided, it is taken as a designator
2416     for a list of additional domain names that can be used to access
2417     the distribution.
2418
2419     <p>If <var>enabled</var> is NIL, the distribution is initially
2420       created in a disabled state. The default value is is T.
2421
2422     <p>If <var>comment</var> is provided, it becomes part of the newly
2423       created distribution.
2424   </blockquote>
2425 </div>
2426
2427 <div class='item'>
2428   <div class='type'><a name='delete-distribution'>[Function]</a></div>
2429   <div class='signature'>
2430     <code class='name'>delete-distribution</code>
2431     <span class='args'>
2432       <var>distribution</var>
2433     </span>
2434     <span class='result'>=> |</span>
2435   </div>
2436
2437   <blockquote class='description'>
2438     <p>Deletes <var>distribution</var>. Distributions must be disabled
2439       before deletion; see <a href='#disable'><tt>DISABLE</tt></a>.
2440   </blockquote>
2441 </div>
2442
2443
2444 <div class='item'>
2445   <div class='type'><a name='refresh'>[Function]</a></div>
2446   <div class='signature'>
2447     <code class='name'>refresh</code>
2448     <span class='args'>
2449       <var>distribution</var>
2450     </span>
2451     <span class='result'>=> <var>distribution</var></span>
2452   </div>
2453
2454   <blockquote class='description'>
2455     <p>Queries Amazon for the latest information
2456     regarding <var>distribution</var> and destructively modifies the
2457     instance with the new information. Returns its argument.
2458   </blockquote>
2459 </div>
2460
2461
2462 <div class='item'>
2463   <div class='type'><a name='enable'>[Function]</a></div>
2464   <div class='signature'>
2465     <code class='name'>enable</code>
2466     <span class='args'>
2467       <var>distribution</var>
2468     </span>
2469     <span class='result'>=> |</span>
2470   </div>
2471
2472   <blockquote class='description'>
2473     <p>Enables <var>distribution</var>.
2474   </blockquote>
2475 </div>
2476
2477
2478 <div class='item'>
2479   <div class='type'><a name='disable'>[Function]</a></div>
2480   <div class='signature'>
2481     <code class='name'>disable</code>
2482     <span class='args'>
2483       <var>distribution</var>
2484     </span>
2485     <span class='result'>=> |</span>
2486   </div>
2487
2488   <blockquote class='description'>
2489     <p>Disables <var>distribution</var>.
2490   </blockquote>
2491 </div>
2492
2493
2494 <div class='item'>
2495   <div class='type'><a name='ensure-cname'>[Function]</a></div>
2496   <div class='signature'>
2497     <code class='name'>ensure-cname</code>
2498     <span class='args'>
2499       <var>distribution</var>
2500       <var>cname</var>
2501     </span>
2502     <span class='result'>=> |</span>
2503   </div>
2504
2505   <blockquote class='description'>
2506     <p>Adds <var>cname</var> to the CNAMEs of <var>distribution</var>,
2507       if necessary.
2508   </blockquote>
2509 </div>
2510
2511 <div class='item'>
2512   <div class='type'><a name='remove-cname'>[Function]</a></div>
2513   <div class='signature'>
2514     <code class='name'>remove-cname</code>
2515     <span class='args'>
2516       <var>distribution</var>
2517       <var>cname</var>
2518     </span>
2519     <span class='result'>=> |</span>
2520   </div>
2521
2522   <blockquote class='description'>
2523     <p>Removes <var>cname</var> from the CNAMEs of <var>distribution</var>.
2524   </blockquote>
2525 </div>
2526
2527
2528 <div class='item'>
2529   <div class='type'><a name='set-comment'>[Function]</a></div>
2530   <div class='signature'>
2531     <code class='name'>set-comment</code>
2532     <span class='args'>
2533       <var>distribution</var>
2534       <var>comment</var>
2535     </span>
2536     <span class='result'>=> |</span>
2537   </div>
2538
2539   <blockquote class='description'>
2540     <p>Sets the comment of <var>distribution</var> to <var>comment</var>.
2541   </blockquote>
2542 </div>
2543
2544
2545 <div class='item'>
2546   <div class='type'><a name='distributions-for-bucket'>[Function]</a></div>
2547   <div class='signature'>
2548     <code class='name'>distributions-for-bucket</code>
2549     <span class='args'>
2550       <var>bucket-name</var>
2551     </span>
2552     <span class='result'>=> |</span>
2553   </div>
2554
2555   <blockquote class='description'>
2556     <p>Returns a list of distributions that
2557       have <var>bucket-name</var> as the origin bucket.
2558   </blockquote>
2559 </div>
2560
2561
2562 <div class='item'>
2563   <div class='type'><a name='distribution-error'>[Condition]</a></div>
2564   <div class='signature'>
2565     <code class='name'>distribution-error</code>
2566   </div>
2567
2568   <blockquote class='description'>
2569     <p>All errors signaled as a result of a CloudFront request error
2570       are subtypes of <tt>distribution-error</tt>.
2571   </blockquote>
2572 </div>
2573
2574
2575 <div class='item'>
2576   <div class='type'><a name='distribution-not-disabled'>[Condition]</a></div>
2577   <div class='signature'>
2578     <code class='name'>distribution-not-disabled</code>
2579   </div>
2580
2581   <blockquote class='description'>
2582     <p>Distributions must be fully disabled before they are
2583       deleted. If they have not been disabled, or the status of the
2584       distribution is still
2585       "InProgress", <tt>distribution-not-disabled</tt> is signaled.
2586   </blockquote>
2587 </div>
2588
2589
2590 <div class='item'>
2591   <div class='type'><a name='cname-already-exists'>[Condition]</a></div>
2592   <div class='signature'>
2593     <code class='name'>cname-already-exists</code>
2594   </div>
2595
2596   <blockquote class='description'>
2597     <p>A CNAME may only appear on one distribution. If you attempt to
2598       add a CNAME to a distribution that is already present on some
2599       other distribution, <tt>cname-already-exists</tt> is signaled.
2600   </blockquote>
2601 </div>
2602
2603
2604 <div class='item'>
2605   <div class='type'><a name='too-many-distributions'>[Condition]</a></div>
2606   <div class='signature'>
2607     <code class='name'>too-many-distributions</code>
2608   </div>
2609
2610   <blockquote class='description'>
2611     <p>If creating a new distribution
2612       via <a href='#create-distribution'><tt>CREATE-DISTRIBUTION</tt></a>
2613       would exceed the account limit of total distributions,
2614       <tt>too-many-distributions</tt> is signaled.
2615   </blockquote>
2616 </div>
2617
2618
2619 <div class='item'>
2620   <div class='type'><a name='status'>[Function]</a></div>
2621   <div class='signature'>
2622     <code class='name'>status</code>
2623     <span class='args'>
2624       <var>distribution</var>
2625     </span>
2626     <span class='result'>=> <var>status</var></span>
2627   </div>
2628
2629   <blockquote class='description'>
2630     <p>Returns a string describing the status
2631       of <var>distribution</var>. The status is either "InProgress",
2632       meaning that the distribution's configuration has not fully
2633       propagated through the CloudFront system, or "Deployed".
2634   </blockquote>
2635 </div>
2636
2637
2638 <div class='item'>
2639   <div class='type'><a name='origin-bucket'>[Function]</a></div>
2640   <div class='signature'>
2641     <code class='name'>origin-bucket</code>
2642     <span class='args'>
2643       <var>distribution</var>
2644     </span>
2645     <span class='result'>=> <var>origin-bucket</var></span>
2646   </div>
2647
2648   <blockquote class='description'>
2649     <p>Returns the origin bucket for <var>distribution</var>. It is
2650       different from a normal ZS3 bucket name, because it has
2651       ".s3.amazonaws.com" as a suffix.
2652   </blockquote>
2653 </div>
2654
2655
2656 <div class='item'>
2657   <div class='type'><a name='domain-name'>[Function]</a></div>
2658   <div class='signature'>
2659     <code class='name'>domain-name</code>
2660     <span class='args'>
2661       <var>distribution</var>
2662     </span>
2663     <span class='result'>=> <var>domain-name</var></span>
2664   </div>
2665
2666   <blockquote class='description'>
2667     <p>Returns the domain name through which CloudFront-enabled access
2668       to a resource may be made.
2669   </blockquote>
2670 </div>
2671
2672
2673 <div class='item'>
2674   <div class='type'><a name='cnames'>[Function]</a></div>
2675   <div class='signature'>
2676     <code class='name'>cnames</code>
2677     <span class='args'>
2678       <var>distribution</var>
2679     </span>
2680     <span class='result'>=> <var>cnames</var></span>
2681   </div>
2682
2683   <blockquote class='description'>
2684     Returns a list of CNAMEs associated with <var>distribution</var>.
2685   </blockquote>
2686 </div>
2687
2688
2689 <div class='item'>
2690   <div class='type'><a name='enabledp'>[Function]</a></div>
2691   <div class='signature'>
2692     <code class='name'>enabledp</code>
2693     <span class='args'>
2694       <var>distribution</var>
2695     </span>
2696     <span class='result'>=> <var>boolean</var></span>
2697   </div>
2698
2699   <blockquote class='description'>
2700     <p>Returns <i>true</i> if <var>distribution</var> is enabled, NIL
2701       otherwise.
2702   </blockquote>
2703 </div>
2704
2705
2706 <div class='item'>
2707   <div class='type'><a name='invalidate-paths'>[Function]</a></div>
2708   <div class='signature'>
2709     <code class='name'>invalidate-paths</code>
2710     <span class='args'>
2711       <var>distribution</var>
2712       <var>paths</var>
2713     </span>
2714     <span class='result'>=> <var>invalidation</var></span>
2715   </div>
2716
2717   <blockquote class='description'>
2718     <p>Initiates the invalidation of resources identified
2719       by <var>paths</var> in <var>distribution</var>. <var>paths</var>
2720       should consist of key names that correspond to objects in the
2721       distribution's S3 bucket.
2722
2723     <p>The <var>invalidation</var> object reports on the status of the
2724       invalidation request. It can be queried
2725       with <a href='#status'><tt>STATUS</tt></a> and refreshed
2726       with <a href='#refresh'><tt>REFRESH</tt></a>.
2727
2728 <pre class='code'>
2729 * <b>(invalidate-paths distribution '("/css/site.css" "/js/site.js"))</b>
2730 #&lt;INVALIDATION "I1HJC711OFAVKO" [InProgress]>
2731 * <b>(progn (sleep 300) (refresh *))</b>
2732 #&lt;INVALIDATION "I1HJC711OFAVKO" [Completed]>
2733 </pre>
2734   </blockquote>
2735 </div>
2736
2737
2738
2739
2740 <a name='references'><h2>References</h2></a>
2741
2742   <ul>
2743     <li> Amazon, <a href="http://developer.amazonwebservices.com/connect/entry.jspa?externalID=123&categoryID=48">Amazon
2744    S3 Technical Documentation</a>
2745     <li> Amazon, <a href="http://developer.amazonwebservices.com/connect/entry.jspa?externalID=1876&categoryID=213">Amazon CloudFront Technical Documentation</a>
2746   </ul>
2747
2748
2749
2750
2751 <a name='acknowledgements'><h2>Acknowledgements</h2>
2752
2753   <p>Several people on <a href='http://freenode.net/'>freenode</a>
2754     #lisp pointed out typos and glitches in this
2755     documentation. Special thanks to Bart "_3b" Botta for providing a
2756     detailed documentation review that pointed out glitches,
2757     omissions, and overly confusing passages.
2758
2759   <p>James Wright corrected a problem with computing the string to
2760     sign and URL encoding.
2761
2762 <a name='feedback'><h2>Feedback</h2></a>
2763
2764   <p>If you have any questions or comments about ZS3, please email
2765   me, <a href='mailto:xach@xach.com'>Zach Beane</a>
2766
2767   <p>For ZS3 announcements and development discussion, please see the
2768   <a href="http://groups.google.com/group/zs3-devel">zs3-devel</a>
2769   mailing list.
2770
2771   <p><i>2010-09-03</i>
2772
2773  <p class='copyright'>Copyright &copy; 2008-2010 Zachary Beane, All Rights Reserved
2774
2775
2776 </div>
2777 </body>
2778 </html>
2779