# frozen_string_literal: true

#-------------------------------------------------------------------------
# # Copyright (c) Microsoft and contributors. All rights reserved.
#
# The MIT License(MIT)

# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files(the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions :

# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.

# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.
#--------------------------------------------------------------------------

module Azure::Storage::Blob
  module Container
    include Azure::Storage::Common::Service

    class Container
      def initialize
        @properties = {}
        @metadata = {}
        yield self if block_given?
      end

      attr_accessor :name
      attr_accessor :properties
      attr_accessor :metadata
      attr_accessor :public_access_level
    end

    # Public: Create a new container
    #
    # ==== Attributes
    #
    # * +name+                      - String. The name of the container.
    # * +options+                   - Hash. Optional parameters.
    #
    # ==== Options
    #
    # Accepted key/value pairs in options parameter are:
    # * +:metadata+                 - Hash. User defined metadata for the container (optional).
    # * +:public_access_level+      - String. One of "container" or "blob" (optional).
    # * +:timeout+                  - Integer. A timeout in seconds.
    # * +:request_id+               - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
    #                                 in the analytics logs when storage analytics logging is enabled.
    #
    # See http://msdn.microsoft.com/en-us/library/azure/dd179468.aspx
    #
    # Returns a Container
    def create_container(name, options = {})
      # Query
      query = {}
      query["timeout"] = options[:timeout].to_s if options[:timeout]

      # Scheme + path
      uri = container_uri(name, query)

      # Headers
      headers = {}
      StorageService.add_metadata_to_headers(options[:metadata], headers) if options[:metadata]
      headers["x-ms-blob-public-access"] = options[:public_access_level].to_s if options[:public_access_level]

      # Call
      response = call(:put, uri, nil, headers, options)

      # result
      container = Serialization.container_from_headers(response.headers)
      container.name = name
      container.metadata = options[:metadata]
      container
    end

    # Public: Returns all properties and metadata on the container.
    #
    # ==== Attributes
    #
    # * +name+                      - String. The name of the container
    # * +options+                   - Hash. Optional parameters.
    #
    # ==== Options
    #
    # Accepted key/value pairs in options parameter are:
    # * +:timeout+                  - Integer. A timeout in seconds.
    # * +:request_id+               - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
    #                                 in the analytics logs when storage analytics logging is enabled.
    # * +:location_mode+            - LocationMode. Specifies the location mode used to decide
    #                                 which location the request should be sent to.
    # * +:lease_id+                 - String. If specified, Get Container Properties only succeeds if the container’s lease is
    #                                 active and matches this ID. If there is no active lease or the ID does not match, 412
    #                                 (Precondition Failed) is returned.
    #
    # See http://msdn.microsoft.com/en-us/library/azure/dd179370.aspx
    #
    # Returns a Container
    def get_container_properties(name, options = {})
      # Query
      query = {}
      query["timeout"] = options[:timeout].to_s if options[:timeout]

      headers = options[:lease_id] ? { "x-ms-lease-id" => options[:lease_id] } : {}

      # Call
      options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
      response = call(:get, container_uri(name, query, options), nil, headers, options)

      # result
      container = Serialization.container_from_headers(response.headers)
      container.name = name
      container
    end

    # Public: Returns only user-defined metadata for the specified container.
    #
    # ==== Attributes
    #
    # * +name+                      - String. The name of the container
    # * +options+                   - Hash. Optional parameters.
    #
    # ==== Options
    #
    # Accepted key/value pairs in options parameter are:
    # * +:timeout+                  - Integer. A timeout in seconds.
    # * +:request_id+               - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
    #                                 in the analytics logs when storage analytics logging is enabled.
    # * +:location_mode+            - LocationMode. Specifies the location mode used to decide
    #                                 which location the request should be sent to.
    # * +:lease_id+                 - String. If specified, Get Container Metadata only succeeds if the container’s lease is
    #                                 active and matches this ID. If there is no active lease or the ID does not match, 412
    #                                 (Precondition Failed) is returned.
    #
    # See http://msdn.microsoft.com/en-us/library/azure/ee691976.aspx
    #
    # Returns a Container
    def get_container_metadata(name, options = {})
      # Query
      query = { "comp" => "metadata" }
      query["timeout"] = options[:timeout].to_s if options[:timeout]

      headers = options[:lease_id] ? { "x-ms-lease-id" => options[:lease_id] } : {}

      # Call
      options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
      response = call(:get, container_uri(name, query, options), nil, headers, options)

      # result
      container = Serialization.container_from_headers(response.headers)
      container.name = name
      container
    end

    # Public: Sets custom metadata for the container.
    #
    # ==== Attributes
    #
    # * +name+                      - String. The name of the container
    # * +metadata+                  - Hash. A Hash of the metadata values
    # * +options+                   - Hash. Optional parameters.
    #
    # ==== Options
    #
    # Accepted key/value pairs in options parameter are:
    # * +:timeout+                  - Integer. A timeout in seconds.
    # * +:request_id+               - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
    #                                 in the analytics logs when storage analytics logging is enabled.
    # * +:lease_id+                 - String. If specified, Set Container Metadata only succeeds if the container’s lease is
    #                                 active and matches this ID. If there is no active lease or the ID does not match, 412
    #                                 (Precondition Failed) is returned.
    #
    # See http://msdn.microsoft.com/en-us/library/azure/dd179362.aspx
    #
    # Returns nil on success
    def set_container_metadata(name, metadata, options = {})
      # Query
      query = { "comp" => "metadata" }
      query["timeout"] = options[:timeout].to_s if options[:timeout]

      # Headers
      headers = {}
      StorageService.add_metadata_to_headers(metadata, headers) if metadata
      headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]

      # Call
      call(:put, container_uri(name, query), nil, headers, options)

      # Result
      nil
    end

    # Public: Gets the access control list (ACL) and any container-level access policies
    # for the container.
    #
    # ==== Attributes
    #
    # * +name+                      - String. The name of the container
    # * +options+                   - Hash. Optional parameters.
    #
    # ==== Options
    #
    # Accepted key/value pairs in options parameter are:
    # * +:timeout+                  - Integer. A timeout in seconds.
    # * +:request_id+               - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
    #                                 in the analytics logs when storage analytics logging is enabled.
    # * +:location_mode+            - LocationMode. Specifies the location mode used to decide
    #                                 which location the request should be sent to.
    # * +:lease_id+                 - String. If specified, Get Container ACL only succeeds if the container’s lease is
    #                                 active and matches this ID. If there is no active lease or the ID does not match, 412
    #                                 (Precondition Failed) is returned.
    #
    # See http://msdn.microsoft.com/en-us/library/azure/dd179469.aspx
    #
    # Returns a tuple of (container, signed_identifiers)
    #   container           - A Azure::Storage::Entity::Blob::Container instance
    #   signed_identifiers  - A list of Azure::Storage::Entity::SignedIdentifier instances
    #
    def get_container_acl(name, options = {})
      # Query
      query = { "comp" => "acl" }
      query["timeout"] = options[:timeout].to_s if options[:timeout]

      headers = options[:lease_id] ? { "x-ms-lease-id" => options[:lease_id] } : {}

      # Call
      options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
      response = call(:get, container_uri(name, query, options), nil, headers, options)

      # Result
      container = Serialization.container_from_headers(response.headers)
      container.name = name

      signed_identifiers = nil
      signed_identifiers = Serialization.signed_identifiers_from_xml(response.body) if response.body != nil && response.body.length > 0

      return container, signed_identifiers
    end

    # Public: Sets the ACL and any container-level access policies for the container.
    #
    # ==== Attributes
    #
    # * +name+                         - String. The name of the container
    # * +public_access_level+          - String. The container public access level
    # * +options+                      - Hash. Optional parameters.
    #
    # ==== Options
    #
    # Accepted key/value pairs in options parameter are:
    # * +:signed_identifiers+          - Array. A list of Azure::Storage::Entity::SignedIdentifier instances (optional)
    # * +:timeout+                     - Integer. A timeout in seconds.
    # * +:request_id+                  - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
    #                                    in the analytics logs when storage analytics logging is enabled.
    # * +:lease_id+                    - String. If specified, Set Container ACL only succeeds if the container’s lease is
    #                                    active and matches this ID. If there is no active lease or the ID does not match, 412
    #                                    (Precondition Failed) is returned.
    #
    # See http://msdn.microsoft.com/en-us/library/azure/dd179391.aspx
    #
    # Returns a tuple of (container, signed_identifiers)
    # * +container+                    - A Azure::Storage::Entity::Blob::Container instance
    # * +signed_identifiers+           - A list of Azure::Storage::Entity::SignedIdentifier instances
    #
    def set_container_acl(name, public_access_level, options = {})
      # Query
      query = { "comp" => "acl" }
      query["timeout"] = options[:timeout].to_s if options[:timeout]

      # Scheme + path
      uri = container_uri(name, query)

      # Headers + body
      headers = {}
      headers["x-ms-blob-public-access"] = public_access_level if public_access_level && public_access_level.to_s.length > 0
      headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]

      signed_identifiers = nil
      signed_identifiers = options[:signed_identifiers] if options[:signed_identifiers]

      body = nil
      body = Serialization.signed_identifiers_to_xml(signed_identifiers) if signed_identifiers

      # Call
      response = call(:put, uri, body, headers, options)

      # Result
      container = Serialization.container_from_headers(response.headers)
      container.name = name
      container.public_access_level = public_access_level

      return container, signed_identifiers || []
    end

    # Public: Deletes a container.
    #
    # ==== Attributes
    #
    # * +name+                      - String. The name of the container.
    # * +options+                   - Hash. Optional parameters.
    #
    # ==== Options
    #
    # Accepted key/value pairs in options parameter are:
    # * +:timeout+                  - Integer. A timeout in seconds.
    # * +:request_id+               - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
    #                                 in the analytics logs when storage analytics logging is enabled.
    # * +:lease_id+                 - String. Required for version 2012-02-12 and newer if the container has an active lease. To call
    #                                 Delete Container on a container that has an active lease, specify the lease ID in this header.
    #                                 If this header is not specified when there is an active lease, Delete Container will return 409
    #                                 (Conflict). If you specify the wrong lease ID, or a lease ID on a container that does not have
    #                                 an active lease, Delete Container will return 412 (Precondition failed).
    #
    # See http://msdn.microsoft.com/en-us/library/azure/dd179408.aspx
    #
    # Returns nil on success
    def delete_container(name, options = {})
      # Query
      query = {}
      query["timeout"] = options[:timeout].to_s if options[:timeout]

      headers = options[:lease_id] ? { "x-ms-lease-id" => options[:lease_id] } : {}

      # Call
      call(:delete, container_uri(name, query), nil, headers, options)

      # result
      nil
    end

    # Public: Establishes an exclusive write lock on a container. The lock duration can be 15 to 60 seconds, or can be infinite.
    # To write to a locked container, a client must provide a lease ID.
    #
    # ==== Attributes
    #
    # * +container+                  - String. The container name.
    # * +options+                    - Hash. Optional parameters.
    #
    # ==== Options
    #
    # Accepted key/value pairs in options parameter are:
    # * +:duration+                  - Integer. Default -1. Specifies the duration of the lease, in seconds, or negative one (-1)
    #                                  for a lease that never expires. A non-infinite lease can be between 15 and 60 seconds. (optional)
    # * +:proposed_lease_id+         - String. Proposed lease ID, in a GUID string format. The Blob service returns 400 (Invalid request)
    #                                  if the proposed lease ID is not in the correct format. (optional)
    # * +:timeout+                   - Integer. A timeout in seconds.
    # * +:request_id+                - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
    #                                  in the analytics logs when storage analytics logging is enabled.
    # * +:if_modified_since+         - String. A DateTime value. Specify this conditional header to acquire the lease
    #                                  only if the container has been modified since the specified date/time. If the container has not been modified,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:if_unmodified_since+       - String. A DateTime value. Specify this conditional header to acquire the lease
    #                                  only if the container has not been modified since the specified date/time. If the container has been modified,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:if_match+                  - String. An ETag value. Specify an ETag value for this conditional header to acquire the lease
    #                                  only if the container's ETag value matches the value specified. If the values do not match,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:if_none_match+             - String. An ETag value. Specify an ETag value for this conditional header to acquire the lease
    #                                  only if the container's ETag value does not match the value specified. If the values are identical,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:origin+                    - String. Optional. Specifies the origin from which the request is issued. The presence of this header results
    #                                  in cross-origin resource sharing headers on the response.
    #
    # See http://msdn.microsoft.com/en-us/library/azure/ee691972.aspx
    #
    # Returns a String of the new unique lease id. While the lease is active, you must include the lease ID with any request
    # to write, or to renew, change, or release the lease.
    #
    def acquire_container_lease(container, options = {})
      acquire_lease container, nil, options
    end

    # Public: Renews the lease. The lease can be renewed if the lease ID specified on the request matches that
    # associated with the container. Note that the lease may be renewed even if it has expired as long as the container
    # has not been modified or leased again since the expiration of that lease. When you renew a lease, the
    # lease duration clock resets.
    #
    # ==== Attributes
    #
    # * +container+                  - String. The container name.
    # * +lease+                      - String. The lease id
    # * +options+                    - Hash. Optional parameters.
    #
    # ==== Options
    #
    # Accepted key/value pairs in options parameter are:
    # * +:timeout+                   - Integer. A timeout in seconds.
    # * +:request_id+                - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
    #                                  in the analytics logs when storage analytics logging is enabled.
    # * +:if_modified_since+         - String. A DateTime value. Specify this conditional header to renew the lease
    #                                  only if the container has been modified since the specified date/time. If the container has not been modified,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:if_unmodified_since+       - String. A DateTime value. Specify this conditional header to renew the lease
    #                                  only if the container has not been modified since the specified date/time. If the container has been modified,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:if_match+                  - String. An ETag value. Specify an ETag value for this conditional header to renew the lease
    #                                  only if the container's ETag value matches the value specified. If the values do not match,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:if_none_match+             - String. An ETag value. Specify an ETag value for this conditional header to renew the lease
    #                                  only if the container's ETag value does not match the value specified. If the values are identical,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:origin+                    - String. Optional. Specifies the origin from which the request is issued. The presence of this header results
    #                                  in cross-origin resource sharing headers on the response.
    # See http://msdn.microsoft.com/en-us/library/azure/ee691972.aspx
    #
    # Returns the renewed lease id
    def renew_container_lease(container, lease, options = {})
      renew_lease container, nil, lease, options
    end

    # Public: Change the lease ID.
    #
    # ==== Attributes
    #
    # * +container+                  - String. The container name.
    # * +lease+                      - String. The existing lease id.
    # * +proposed_lease+             - String. Proposed lease ID, in a GUID string format. The Blob service returns 400 (Invalid request)
    #                                  if the proposed lease ID is not in the correct format. (optional).
    # * +options+                    - Hash. Optional parameters.
    #
    # ==== Options
    #
    # Accepted key/value pairs in options parameter are:
    # * +:timeout+                   - Integer. A timeout in seconds.
    # * +:request_id+                - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
    #                                  in the analytics logs when storage analytics logging is enabled.
    # * +:if_modified_since+         - String. A DateTime value. Specify this conditional header to change the lease
    #                                  only if the container has been modified since the specified date/time. If the container has not been modified,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:if_unmodified_since+       - String. A DateTime value. Specify this conditional header to change the lease
    #                                  only if the container has not been modified since the specified date/time. If the container has been modified,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:if_match+                  - String. An ETag value. Specify an ETag value for this conditional header to change the lease
    #                                  only if the container's ETag value matches the value specified. If the values do not match,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:if_none_match+             - String. An ETag value. Specify an ETag value for this conditional header to change the lease
    #                                  only if the container's ETag value does not match the value specified. If the values are identical,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:origin+                    - String. Optional. Specifies the origin from which the request is issued. The presence of this header results
    #                                  in cross-origin resource sharing headers on the response.
    # See http://msdn.microsoft.com/en-us/library/azure/ee691972.aspx
    #
    # Returns the changed lease id
    def change_container_lease(container, lease, proposed_lease, options = {})
      change_lease container, nil, lease, proposed_lease, options
    end

    # Public: Releases the lease. The lease may be released if the lease ID specified on the request matches that
    # associated with the container. Releasing the lease allows another client to immediately acquire the lease for
    # the container as soon as the release is complete.
    #
    # ==== Attributes
    #
    # * +container+                  - String. The container name.
    # * +lease+                      - String. The lease id.
    # * +options+                    - Hash. Optional parameters.
    #
    # ==== Options
    #
    # Accepted key/value pairs in options parameter are:
    # * +:timeout+                   - Integer. A timeout in seconds.
    # * +:request_id+                - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
    #                                  in the analytics logs when storage analytics logging is enabled.
    # * +:if_modified_since+         - String. A DateTime value. Specify this conditional header to release the lease
    #                                  only if the container has been modified since the specified date/time. If the container has not been modified,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:if_unmodified_since+       - String. A DateTime value. Specify this conditional header to release the lease
    #                                  only if the container has not been modified since the specified date/time. If the container has been modified,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:if_match+                  - String. An ETag value. Specify an ETag value for this conditional header to release the lease
    #                                  only if the container's ETag value matches the value specified. If the values do not match,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:if_none_match+             - String. An ETag value. Specify an ETag value for this conditional header to release the lease
    #                                  only if the container's ETag value does not match the value specified. If the values are identical,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:origin+                    - String. Optional. Specifies the origin from which the request is issued. The presence of this header results
    #                                  in cross-origin resource sharing headers on the response.
    # See http://msdn.microsoft.com/en-us/library/azure/ee691972.aspx
    #
    # Returns nil on success
    def release_container_lease(container, lease, options = {})
      release_lease container, nil, lease, options
    end

    # Public: Breaks the lease, if the container has an active lease. Once a lease is broken, it cannot be renewed. Any
    # authorized request can break the lease; the request is not required to specify a matching lease ID. When a
    # lease is broken, the lease break period is allowed to elapse, during which time no lease operation except
    # break and release can be performed on the container. When a lease is successfully broken, the response indicates
    # the interval in seconds until a new lease can be acquired.
    #
    # A lease that has been broken can also be released, in which case another client may immediately acquire the
    # lease on the container.
    #
    # ==== Attributes
    #
    # * +container+                  - String. The container name.
    # * +options+                    - Hash. Optional parameters.
    #
    # ==== Options
    #
    # Accepted key/value pairs in options parameter are:
    # * +:break_period+              - Integer. The proposed duration of seconds that the lease should continue before it is
    #                                  broken, between 0 and 60 seconds. This break period is only used if it is shorter than
    #                                  the time remaining on the lease. If longer, the time remaining on the lease is used. A
    #                                  new lease will not be available before the break period has expired, but the lease may
    #                                  be held for longer than the break period.
    #
    #                                  If this option is not used, a fixed-duration lease breaks after the remaining lease
    #                                  period elapses, and an infinite lease breaks immediately.
    # * +:timeout+                   - Integer. A timeout in seconds.
    # * +:request_id+                - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
    #                                  in the analytics logs when storage analytics logging is enabled.
    # * +:if_modified_since+         - String. A DateTime value. Specify this conditional header to break the lease
    #                                  only if the container has been modified since the specified date/time. If the container has not been modified,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:if_unmodified_since+       - String. A DateTime value. Specify this conditional header to break the lease
    #                                  only if the container has not been modified since the specified date/time. If the container has been modified,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:if_match+                  - String. An ETag value. Specify an ETag value for this conditional header to break the lease
    #                                  only if the container's ETag value matches the value specified. If the values do not match,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:if_none_match+             - String. An ETag value. Specify an ETag value for this conditional header to break the lease
    #                                  only if the container's ETag value does not match the value specified. If the values are identical,
    #                                  the Blob service returns status code 412 (Precondition Failed).
    # * +:origin+                    - String. Optional. Specifies the origin from which the request is issued. The presence of this header results
    #                                  in cross-origin resource sharing headers on the response.
    # See http://msdn.microsoft.com/en-us/library/azure/ee691972.aspx
    #
    # Returns an Integer of the remaining lease time. This value is the approximate time remaining in the lease
    # period, in seconds. This header is returned only for a successful request to break the lease. If the break
    # is immediate, 0 is returned.
    def break_container_lease(container, options = {})
      break_lease container, nil, options
    end

    # Public: Get a list of Blobs from the server
    #
    # ==== Attributes
    #
    # * +name+              - String. The name of the container to list blobs for.
    # * +options+           - Hash. Optional parameters.
    #
    # ==== Options
    #
    # Accepted key/value pairs in options parameter are:
    # * +:prefix+           - String. Filters the results to return only blobs
    #                         whose name begins with the specified prefix. (optional)
    # * +:delimiter+        - String. When the request includes this parameter, the operation
    #                         returns a BlobPrefix element in the response body that acts as a
    #                         placeholder for all blobs whose names begin with the same substring
    #                         up to the appearance of the delimiter character. The delimiter may
    #                         be a single character or a string.
    # * +:marker+           - String. An identifier that specifies the portion of the
    #                         list to be returned. This value comes from the property
    #                         Azure::Storage::Common::EnumerationResults.continuation_token when
    #                         there are more blobs available than were returned. The
    #                         marker value may then be used here to request the next set
    #                         of list items. (optional)
    # * +:max_results+      - Integer. Specifies the maximum number of blobs to return.
    #                         If max_results is not specified, or is a value greater than
    #                         5,000, the server will return up to 5,000 items. If it is set
    #                         to a value less than or equal to zero, the server will return
    #                         status code 400 (Bad Request). (optional)
    # * +:metadata+         - Boolean. Specifies whether or not to return the blob metadata.
    #                         (optional, Default=false)
    # * +:snapshots+        - Boolean. Specifies that snapshots should be included in the
    #                         enumeration. Snapshots are listed from oldest to newest in the
    #                         response. (optional, Default=false)
    # * +:uncomittedblobs+  - Boolean. Specifies that blobs for which blocks have been uploaded,
    #                         but which have not been committed using put_block_list, be included
    #                         in the response. (optional, Default=false)
    # * +:copy+             - Boolean. Specifies that metadata related to any current or previous
    #                         copy_blob operation should be included in the response.
    #                         (optional, Default=false)
    # * +:timeout+          - Integer. A timeout in seconds.
    # * +:request_id+       - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
    #                         in the analytics logs when storage analytics logging is enabled.
    # * +:location_mode+    - LocationMode. Specifies the location mode used to decide
    #                         which location the request should be sent to.
    #
    # NOTE: Metadata requested with the :metadata parameter must have been stored in
    # accordance with the naming restrictions imposed by the 2009-09-19 version of the Blob
    # service. Beginning with that version, all metadata names must adhere to the naming
    # conventions for C# identifiers.
    #
    # See: http://msdn.microsoft.com/en-us/library/azure/dd135734.aspx
    #
    # Any metadata with invalid names which were previously stored, will be returned with the
    # key "x-ms-invalid-name" in the metadata hash. This may contain multiple values and be an
    # Array (vs a String if it only contains a single value).
    #
    # Returns an Azure::Storage::Common::EnumerationResults
    def list_blobs(name, options = {})
      # Query
      query = { "comp" => "list" }
      query["prefix"] = options[:prefix].gsub(/\\/, "/") if options[:prefix]
      query["delimiter"] = options[:delimiter] if options[:delimiter]
      query["marker"] = options[:marker] if options[:marker]
      query["maxresults"] = options[:max_results].to_s if options[:max_results]
      query["timeout"] = options[:timeout].to_s if options[:timeout]

      included_datasets = []
      included_datasets.push("metadata") if options[:metadata] == true
      included_datasets.push("snapshots") if options[:snapshots] == true
      included_datasets.push("uncommittedblobs") if options[:uncommittedblobs] == true
      included_datasets.push("copy") if options[:copy] == true

      query["include"] = included_datasets.join "," if included_datasets.length > 0

      # Scheme + path
      options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
      uri = container_uri(name, query, options)

      # Call
      response = call(:get, uri, nil, {}, options)

      # Result
      if response.success?
        Serialization.blob_enumeration_results_from_xml(response.body)
      else
        response.exception
      end
    end
  end
end