-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

-- | Interface to Amazon's Simple Storage Service (S3)
--   
--   This is the Haskell S3 library. It provides an interface to Amazon's
--   Simple Storage Service (S3), allowing Haskell developers to reliably
--   store and retrieve arbitrary amounts of data from anywhere on the
--   Internet.
@package hS3
@version 0.5.7

-- | Helper functions for working with HXT. Scraped from
--   haskell.org.
module Network.AWS.ArrowUtils
split :: Arrow a => a b (b, b)
unsplit :: Arrow a => (b -> c -> d) -> a (b, c) d
atTag :: ArrowXml a => String -> a (NTree XNode) XmlTree
text :: ArrowXml cat => cat (NTree XNode) String

-- | Connection and authentication info for an Amazon AWS request.
module Network.AWS.AWSConnection

-- | Hostname used for connecting to Amazon's production S3 service
--   (s3.amazonaws.com).
defaultAmazonS3Host :: String

-- | Port number used for connecting to Amazon's production S3 service
--   (80).
defaultAmazonS3Port :: Int

-- | Create an AWSConnection to Amazon from credentials. Uses the
--   production service.
amazonS3Connection :: String -> String -> AWSConnection

-- | Retrieve Access and Secret keys from environment variables
--   AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, respectively. Either
--   variable being undefined or empty will result in Nothing.
amazonS3ConnectionFromEnv :: IO (Maybe AWSConnection)

-- | An Amazon Web Services connection. Everything needed to connect and
--   authenticate requests.
data AWSConnection
AWSConnection :: String -> Int -> String -> String -> AWSConnection

-- | Service provider hostname
awsHost :: AWSConnection -> String

-- | Service provider port number
awsPort :: AWSConnection -> Int

-- | Access Key ID
awsAccessKey :: AWSConnection -> String

-- | Secret Access Key
awsSecretKey :: AWSConnection -> String
instance Show AWSConnection

-- | Results from a query to Amazon Web Services. API Version 2006-03-01
--   http://docs.amazonwebservices.com/AmazonS3/2006-03-01/
module Network.AWS.AWSResult

-- | A result from processing a request to S3. Either some success value,
--   or a ReqError.
type AWSResult a = Either ReqError a

-- | An error from an S3 request, either at the network layer, or from S3
--   itself.
data ReqError

-- | Connection error at the network layer.
NetworkError :: ConnError -> ReqError

-- | AWSError code message constructs an error message from S3
--   itself. See
--   http://docs.amazonwebservices.com/AmazonS3/2006-03-01/ErrorCodeList.html
--   for a detailed list of possible codes.
AWSError :: String -> String -> ReqError

-- | Pretty print an error message.
prettyReqError :: ReqError -> String
instance Show ReqError
instance Eq ReqError

-- | Implements authentication and low-level communication with Amazon Web
--   Services, such as S3, EC2, and others. API Version 2006-03-01
--   http://docs.amazonwebservices.com/AmazonS3/2006-03-01/
module Network.AWS.Authentication

-- | Construct the request specified by an S3Action, send to Amazon, and
--   return the response. Todo: add MD5 signature.
runAction :: S3Action -> IO (AWSResult (HTTPResponse ByteString))

-- | Determine if a header belongs in the StringToSign
isAmzHeader :: Header -> Bool

-- | Construct a pre-signed URI, but don't act on it. This is useful for
--   when an expiration date has been set, and the URI needs to be passed
--   on to a client.
preSignedURI :: S3Action -> Integer -> URI

-- | An action to be performed using S3.
data S3Action
S3Action :: AWSConnection -> String -> String -> String -> [(String, String)] -> ByteString -> RequestMethod -> S3Action

-- | Connection and authentication information
s3conn :: S3Action -> AWSConnection

-- | Name of bucket to act on (URL encoded)
s3bucket :: S3Action -> String

-- | Name of object to act on (URL encoded)
s3object :: S3Action -> String

-- | Query parameters (requires a prefix of ?)
s3query :: S3Action -> String

-- | Additional header fields to send
s3metadata :: S3Action -> [(String, String)]

-- | Body of action, if sending data
s3body :: S3Action -> ByteString

-- | Type of action, PUT, GET, etc.
s3operation :: S3Action -> RequestMethod
mimeEncodeQP :: String -> String

-- | Decode a mime string, we know about quoted printable and base64
--   encoded UTF-8 S3 may convert quoted printable to base64
mimeDecode :: String -> String
instance Show S3Action

-- | Object interface for Amazon S3 API Version 2006-03-01
--   http://docs.amazonwebservices.com/AmazonS3/2006-03-01/
module Network.AWS.S3Object

-- | Send data for an object. If the header Content-Length is not
--   set, all content must be read into memory prior to sending.
sendObject :: AWSConnection -> S3Object -> IO (AWSResult ())

-- | Copy object from one bucket to another (or the same bucket),
--   preserving the original headers. Headers from destobj are
--   sent, while only the bucket and name of srcobj are used. For
--   the best performance, when changing headers during a copy, use the
--   copyObjectWithReplace function. For conditional copying, the
--   following headers set on the destination object may be used:
--   x-amz-copy-source-if-match,
--   x-amz-copy-source-if-none-match,
--   x-amz-copy-source-if-unmodified-since, or
--   x-amz-copy-source-if-modified-since. See
--   http://docs.amazonwebservices.com/AmazonS3/2006-03-01/API/index.html?RESTObjectCOPY.html
--   for more details.
copyObject :: AWSConnection -> S3Object -> S3Object -> IO (AWSResult S3Object)

-- | Copy object from one bucket to another (or the same bucket), replacing
--   headers. Any headers from srcobj are ignored, and only those
--   set in destobj are used.
copyObjectWithReplace :: AWSConnection -> S3Object -> S3Object -> IO (AWSResult S3Object)

-- | Retrieve an object.
getObject :: AWSConnection -> S3Object -> IO (AWSResult S3Object)

-- | Get object info without retrieving content body from server.
getObjectInfo :: AWSConnection -> S3Object -> IO (AWSResult S3Object)

-- | Delete an object. Only bucket and object name need to be specified in
--   the S3Object. Deletion of a non-existent object does not return an
--   error.
deleteObject :: AWSConnection -> S3Object -> IO (AWSResult ())

-- | Create a pre-signed request URI. Anyone can use this to request an
--   object for the number of seconds specified.
publicUriForSeconds :: AWSConnection -> S3Object -> Integer -> IO URI

-- | Create a pre-signed request URI. Anyone can use this to request an
--   object until the specified date.
publicUriUntilTime :: AWSConnection -> S3Object -> Integer -> URI

-- | Add required headers for the storage class. Use this in combination
--   with sendObject for new objects. To modify the storage class of
--   existing objects, use rewriteStorageClass. Using reduced
--   redundancy for object storage trades off redundancy for storage costs.
setStorageClass :: StorageClass -> S3Object -> S3Object

-- | Retrieve the storage class of a local S3Object. Does not work for
--   objects retrieved with getObject, since the required header
--   values are not returned. Use getObjectStorageClass or
--   listObjects from S3Bucket module to determine storage class
--   of existing objects.
getStorageClass :: S3Object -> Maybe StorageClass

-- | Change the storage class (and only the storage class) of an existing
--   object. This actually performs a copy to the same location, preserving
--   metadata. It is not clear to me whether ACLs are preserved when
--   copying to the same location. For best performance, we must not change
--   other headers during storage class changes.
rewriteStorageClass :: AWSConnection -> StorageClass -> S3Object -> IO (AWSResult S3Object)

-- | An object that can be stored and retrieved from S3.
data S3Object
S3Object :: String -> String -> String -> [(String, String)] -> ByteString -> S3Object

-- | Name of the bucket containing this object
obj_bucket :: S3Object -> String

-- | URI of the object. Subresources (?acl or | ?torrent)
--   should be suffixed onto this name.
obj_name :: S3Object -> String

-- | A standard MIME type describing the format of the contents. If not
--   specified, binary/octet-stream is used.
content_type :: S3Object -> String

-- | Object metadata in (key,value) pairs. Key names should use the prefix
--   x-amz-meta- to be stored with the object. The total HTTP
--   request must be under 4KB, including these headers.
obj_headers :: S3Object -> [(String, String)]

-- | Object data.
obj_data :: S3Object -> ByteString
data StorageClass
STANDARD :: StorageClass
REDUCED_REDUNDANCY :: StorageClass
instance Read S3Object
instance Show S3Object
instance Read StorageClass
instance Show StorageClass
instance Eq StorageClass

-- | Bucket interface for Amazon S3 API Version 2006-03-01
--   http://docs.amazonwebservices.com/AmazonS3/2006-03-01/
module Network.AWS.S3Bucket

-- | Create a new bucket on S3 with the given name.
createBucketIn :: AWSConnection -> String -> String -> IO (AWSResult ())

-- | Create a new bucket on S3 with the given name.
createBucket :: AWSConnection -> String -> IO (AWSResult ())

-- | Create a new bucket on S3 with the given prefix, and a random suffix.
--   This can be used to programatically create buckets without of naming
--   conflicts.
createBucketWithPrefixIn :: AWSConnection -> String -> String -> IO (AWSResult String)

-- | see createBucketWithPrefixIn, but hardcoded for the US
createBucketWithPrefix :: AWSConnection -> String -> IO (AWSResult String)

-- | Delete a bucket with the given name on S3. The bucket must be empty
--   for deletion to succeed.
deleteBucket :: AWSConnection -> String -> IO (AWSResult ())

-- | Physical location of the bucket. US or EU
getBucketLocation :: AWSConnection -> String -> IO (AWSResult String)

-- | Empty a bucket of all objects. Iterates through all objects issuing
--   delete commands, so time is proportional to number of objects in the
--   bucket. At this time, delete requests are free from Amazon.
emptyBucket :: AWSConnection -> String -> IO (AWSResult ())

-- | Return a list of all bucket names and creation dates. S3 allows a
--   maximum of 100 buckets per user.
listBuckets :: AWSConnection -> IO (AWSResult [S3Bucket])

-- | List objects in a bucket, based on parameters from ListRequest.
--   See the Amazon S3 developer resources for in depth explanation of how
--   the fields in ListRequest can be used to query for objects.
--   http://docs.amazonwebservices.com/AmazonS3/2006-03-01/ListingKeysRequest.html
listObjects :: AWSConnection -> String -> ListRequest -> IO (AWSResult (IsTruncated, [ListResult]))

-- | Repeatedly query the server for all objects in a bucket, ignoring the
--   max_keys field.
listAllObjects :: AWSConnection -> String -> ListRequest -> IO (AWSResult [ListResult])

-- | Check Amazon guidelines on bucket naming. (missing test for IP-like
--   names)
isBucketNameValid :: String -> Bool

-- | Retrieve the storage class of an object from S3. For checking more
--   than one object's storage class efficiently, use listObjects.
getObjectStorageClass :: AWSConnection -> S3Object -> IO (AWSResult StorageClass)

-- | Check versioning and MFA configuration of a bucket.
getVersioningConfiguration :: AWSConnection -> String -> IO (AWSResult VersioningConfiguration)

-- | Set the versioning configuration of a bucket (MFA not yet supported).
setVersioningConfiguration :: AWSConnection -> String -> VersioningConfiguration -> IO (AWSResult ())
data S3Bucket
S3Bucket :: String -> String -> S3Bucket
bucket_name :: S3Bucket -> String
bucket_creation_date :: S3Bucket -> String

-- | List request parameters
data ListRequest
ListRequest :: String -> String -> String -> Int -> ListRequest
prefix :: ListRequest -> String
marker :: ListRequest -> String
delimiter :: ListRequest -> String
max_keys :: ListRequest -> Int

-- | Result from listing objects.
data ListResult
ListResult :: String -> String -> String -> Integer -> StorageClass -> ListResult

-- | Name of object
key :: ListResult -> String

-- | Last modification date
last_modified :: ListResult -> String

-- | MD5
etag :: ListResult -> String

-- | Bytes of object data
size :: ListResult -> Integer

-- | Storage class of the object
storageClass :: ListResult -> StorageClass

-- | Is a result set response truncated?
type IsTruncated = Bool
data VersioningConfiguration
VersioningConfiguration :: VersioningStatus -> Bool -> VersioningConfiguration
versioningStatus :: VersioningConfiguration -> VersioningStatus
mfaDeleteEnabled :: VersioningConfiguration -> Bool
data VersioningStatus
VersioningDisabled :: VersioningStatus
VersioningEnabled :: VersioningStatus
VersioningSuspended :: VersioningStatus
instance Show S3Bucket
instance Eq S3Bucket
instance Read VersioningStatus
instance Show VersioningStatus
instance Eq VersioningStatus
instance Read VersioningConfiguration
instance Show VersioningConfiguration
instance Eq VersioningConfiguration
instance Show ListResult
instance Show ListRequest
