diff --git a/sdk/storage/inc/blobs/blob_options.hpp b/sdk/storage/inc/blobs/blob_options.hpp index 4e1293dfa..f6050968e 100644 --- a/sdk/storage/inc/blobs/blob_options.hpp +++ b/sdk/storage/inc/blobs/blob_options.hpp @@ -11,356 +11,1424 @@ namespace Azure { namespace Storage { namespace Blobs { + /** + * @brief Service client options used to initalize BlobServiceClient. + */ struct BlobServiceClientOptions { + /** + * @brief Transport pipeline policies for authentication, retries, etc., that are + * applied to every request. + */ std::vector> policies; }; + /** + * @brief Optional parameters for BlobServiceClient::ListBlobContainers. + */ struct ListBlobContainersOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Specifies a string that filters the results to return only containers whose + * name begins with the specified prefix. + */ Azure::Core::Nullable Prefix; + + /** + * @brief A string value that identifies the portion of the list of containers to be + * returned with the next listing operation. The operation returns a non-empty + * ListContainersSegment.NextMarker value if the listing operation did not return all containers + * remaining to be listed with the current segment. The NextMarker value can be used as the + * value for the Marker parameter in a subsequent call to request the next segment of list + * items. + */ Azure::Core::Nullable Marker; + + /** + * @brief Specifies the maximum number of containers to return. + */ Azure::Core::Nullable MaxResults; + + /** + * @brief Specifies that the container's metadata be returned. + */ std::vector Include; }; + /** + * @brief Optional parameters for BlobServiceClient::GetUserDelegationKey. + */ struct GetUserDelegationKeyOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; }; + /** + * @brief Container client options used to initalize BlobContainerClient. + */ struct BlobContainerClientOptions { + /** + * @brief Transport pipeline policies for authentication, retries, etc., that are + * applied to every request. + */ std::vector> policies; }; + /** + * @brief Optional parameters for BlobContainerClient::Create. + */ struct CreateBlobContainerOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Specifies whether data in the container may be accessed publicly and the level + * of access. + */ Azure::Core::Nullable AccessType; + + /** + * @brief Name-value pairs to associate with the container as metadata. + */ std::map Metadata; }; + /** + * @brief Optional parameters for BlobContainerClient::Delete. + */ struct DeleteBlobContainerOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; }; + /** + * @brief Optional parameters for BlobContainerClient::GetProperties. + */ struct GetBlobContainerPropertiesOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; }; + /** + * @brief Optional parameters for BlobContainerClient::SetMetadata. + */ struct SetBlobContainerMetadataOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; }; + /** + * @brief Optional parameters for BlobContainerClient::ListBlobs. + */ struct ListBlobsOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Specifies a string that filters the results to return only blobs whose + * name begins with the specified prefix. + */ Azure::Core::Nullable Prefix; + + /** + * @brief Used to traverse a virtual hierarchy of blobs as though it were a file + * system. + */ Azure::Core::Nullable Delimiter; + + /** + * @brief A string value that identifies the portion of the list of blobs to be + * returned with the next listing operation. The operation returns a non-empty + * BlobsFlatSegment.NextMarker value if the listing operation did not return all blobs + * remaining to be listed with the current segment. The NextMarker value can be used as the + * value for the Marker parameter in a subsequent call to request the next segment of list + * items. + */ Azure::Core::Nullable Marker; + + /** + * @brief Specifies the maximum number of blobs to return. + */ Azure::Core::Nullable MaxResults; + + /** + * @brief Specifies one or more datasets to include in the response. + */ std::vector Include; }; + /** + * @brief Blob client options used to initalize BlobClient. + */ struct BlobClientOptions { + /** + * @brief Transport pipeline policies for authentication, retries, etc., that are + * applied to every request. + */ std::vector> policies; }; + /** + * @brief Block blob client options used to initalize BlockBlobClient. + */ struct BlockBlobClientOptions : public BlobClientOptions { }; + /** + * @brief Append blob client options used to initalize AppendBlobClient. + */ struct AppendBlobClientOptions : public BlobClientOptions { }; + /** + * @brief Page blob client options used to initalize PageBlobClient. + */ struct PageBlobClientOptions : public BlobClientOptions { }; + /** + * @brief Optional parameters for BlobClient::GetProperties. + */ struct GetBlobPropertiesOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for BlobClient::SetHttpHeaders. + */ struct SetBlobHttpHeadersOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief The MIME content type of the blob. + */ std::string ContentType; + + /** + * @brief Specifies which content encodings have been applied to the blob. + */ std::string ContentEncoding; + + /** + * @brief Specifies the natural languages used by this resource. + */ std::string ContentLanguage; + + /** + * @brief Sets the blob’s MD5 hash. + */ std::string ContentMD5; + + /** + * @brief Sets the blob's cache control. + */ std::string CacheControl; + + /** + * @brief Sets the blob’s Content-Disposition header. + */ std::string ContentDisposition; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for BlobClient::SetMetadata. + */ struct SetBlobMetadataOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for BlobClient::SetAccessTier. + */ struct SetAccessTierOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @beirf Indicates the priority with which to rehydrate an archived blob. The priority + * can be set on a blob only once. This header will be ignored on subsequent requests to the + * same blob. + */ Azure::Core::Nullable RehydratePriority; }; + /** + * @brief Optional parameters for BlobClient::StartCopyFromUri. + */ struct StartCopyFromUriOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Specifies user-defined name-value pairs associated with the blob. If no + * name-value pairs are specified, the operation will copy the metadata from the source blob or + * file to the destination blob. If one or more name-value pairs are specified, the destination + * blob is created with the specified metadata, and metadata is not copied from the source blob + * or file. + */ std::map Metadata; + + /** + * @brief Specify this header to perform the operation only if the resource has an + * active lease mathing this id. + */ Azure::Core::Nullable LeaseId; + + /** + * @brief Specify this header to perform the operation only if the lease id given + * matches the active lease id of the source blob. + */ Azure::Core::Nullable SourceLeaseId; + + /** + * @brief Specifies the tier to be set on the target blob. + */ Azure::Core::Nullable Tier = AccessTier::Unknown; + + /** + * @beirf Indicates the priority with which to rehydrate an archived blob. The priority + * can be set on a blob only once. This header will be ignored on subsequent requests to the + * same blob. + */ Azure::Core::Nullable RehydratePriority; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; + + /** + * @brief Specify this conditional header to copy the blob only if the source blob has + * been modified since the specified date/time. + */ Azure::Core::Nullable SourceIfModifiedSince; + + /** + * @brief Specify this conditional header to copy the blob only if the source blob has + * not been modified since the specified date/time. + */ Azure::Core::Nullable SourceIfUnmodifiedSince; + + /** + * @brief Specify this conditional header to copy the source blob only if its ETag + * matches the value specified. + */ Azure::Core::Nullable SourceIfMatch; + + /** + * @brief Specify this conditional header to copy the blob only if its ETag does not + * match the value specified. + */ Azure::Core::Nullable SourceIfNoneMatch; }; + /** + * @brief Optional parameters for BlobClient::AbortCopyFromUri. + */ struct AbortCopyFromUriOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Specify this header to perform the operation only if the resource has an + * active lease mathing this id. + */ Azure::Core::Nullable LeaseId; }; + /** + * @brief Optional parameters for BlobClient::Download. + */ struct DownloadBlobOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Downloads only the bytes of the blob from this offset. + */ Azure::Core::Nullable Offset; + + /** + * @brief Returns at most this number of bytes of the blob from the offset. Null means + * download until the end. + */ Azure::Core::Nullable Length; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for BlobClient::CreateSnapshot. + */ struct CreateSnapshotOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Specifies user-defined name-value pairs associated with the blob. If no + * name-value pairs are specified, the operation will copy the base blob metadata to the + * snapshot. If one or more name-value pairs are specified, the snapshot is created with the + * specified metadata, and metadata is not copied from the base blob. + */ std::map Metadata; + + /** + * @brief Specify this header to perform the operation only if the resource has an + * active lease mathing this id. + */ Azure::Core::Nullable LeaseId; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for BlobClient::Delete. + */ struct DeleteBlobOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Specifies to delete either the base blob + * and all of its snapshots, or only the blob's snapshots and not the blob itself. Required if + * the blob has associated snapshots. + */ Azure::Core::Nullable DeleteSnapshots; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for BlobClient::Undelete. + */ struct UndeleteBlobOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; }; - struct UploadBlobOptions + /** + * @brief Optional parameters for BlockBlobClient::Upload. + */ + struct UploadBlockBlobOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief An MD5 hash of the blob content. This hash is used to verify the integrity of + * the blob during transport. When this header is specified, the storage service checks the hash + * that has arrived with the one that was sent. + */ Azure::Core::Nullable ContentMD5; + + /** + * @brief A CRC64 hash of the blob content. This hash is used to verify the integrity of + * the blob during transport. When this header is specified, the storage service checks the hash + * that has arrived with the one that was sent. + */ Azure::Core::Nullable ContentCRC64; + + /** + * @brief The standard HTTP header system properties to set. + */ BlobHttpHeaders Properties; + + /** + * @brief Name-value pairs associated with the blob as metadata. + */ std::map Metadata; + + /** + * @brief Indicates the tier to be set on blob. + */ Azure::Core::Nullable Tier; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for BlockBlobClient::StageBlock. + */ struct StageBlockOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief An MD5 hash of the blob content. This hash is used to verify the integrity of + * the blob during transport. When this header is specified, the storage service checks the hash + * that has arrived with the one that was sent. + */ Azure::Core::Nullable ContentMD5; + + /** + * @brief A CRC64 hash of the blob content. This hash is used to verify the integrity of + * the blob during transport. When this header is specified, the storage service checks the hash + * that has arrived with the one that was sent. + */ Azure::Core::Nullable ContentCRC64; }; + /** + * @brief Optional parameters for BlockBlobClient::StageBlockFromUri. + */ struct StageBlockFromUriOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Uploads only the bytes of the source blob from this offset. + */ Azure::Core::Nullable SourceOffset; + + /** + * @brief Uploads this number of bytes of the source blob from the offset. Null means + * upload until the end. + */ Azure::Core::Nullable SourceLength; + + /** + * @brief An MD5 hash of the blob content. This hash is used to verify the integrity of + * the blob during transport. When this header is specified, the storage service checks the hash + * that has arrived with the one that was sent. + */ Azure::Core::Nullable ContentMD5; + + /** + * @brief A CRC64 hash of the blob content. This hash is used to verify the integrity of + * the blob during transport. When this header is specified, the storage service checks the hash + * that has arrived with the one that was sent. + */ Azure::Core::Nullable ContentCRC64; + + /** + * @brief Specify this header to perform the operation only if the resource has an + * active lease mathing this id. + */ Azure::Core::Nullable LeaseId; + + /** + * @brief Specify this conditional header to copy the blob only if the source blob has + * been modified since the specified date/time. + */ Azure::Core::Nullable SourceIfModifiedSince; + + /** + * @brief Specify this conditional header to copy the blob only if the source blob has + * not been modified since the specified date/time. + */ Azure::Core::Nullable SourceIfUnmodifiedSince; + + /** + * @brief Specify this conditional header to copy the source blob only if its ETag + * matches the value specified. + */ Azure::Core::Nullable SourceIfMatch; + + /** + * @brief Specify this conditional header to copy the blob only if its ETag does not + * match the value specified. + */ Azure::Core::Nullable SourceIfNoneMatch; }; + /** + * @brief Optional parameters for BlockBlobClient::CommitBlockList. + */ struct CommitBlockListOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief The standard HTTP header system properties to set. + */ BlobHttpHeaders Properties; + + /** + * @brief Name-value pairs associated with the blob as metadata. + */ std::map Metadata; + + /** + * @brief Indicates the tier to be set on blob. + */ Azure::Core::Nullable Tier; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for BlockBlobClient::GetBlockList. + */ struct GetBlockListOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; Azure::Core::Nullable ListType; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for AppendBlobClient::Create. + */ struct CreateAppendBlobOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief The standard HTTP header system properties to set. + */ BlobHttpHeaders Properties; + + /** + * @brief Name-value pairs associated with the blob as metadata. + */ std::map Metadata; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for AppendBlobClient::AppendBlock. + */ struct AppendBlockOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief An MD5 hash of the blob content. This hash is used to verify the integrity of + * the blob during transport. When this header is specified, the storage service checks the hash + * that has arrived with the one that was sent. + */ Azure::Core::Nullable ContentMD5; + + /** + * @brief A CRC64 hash of the blob content. This hash is used to verify the integrity of + * the blob during transport. When this header is specified, the storage service checks the hash + * that has arrived with the one that was sent. + */ Azure::Core::Nullable ContentCRC64; + + /** + * @brief Specify this header to perform the operation only if the resource has an + * active lease mathing this id. + */ Azure::Core::Nullable LeaseId; + + /** + * @brief Ensures that the AppendBlock operation succeeds only if the append blob's size + * is less than or equal to this value. + */ Azure::Core::Nullable MaxSize; + + /** + * @brief Ensures that the AppendBlock operation succeeds only if the append position is equal + * to this value. + */ Azure::Core::Nullable AppendPosition; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for AppendBlobClient::AppendBlockFromUri. + */ struct AppendBlockFromUriOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Uploads only the bytes of the source blob from this offset. + */ Azure::Core::Nullable SourceOffset; + + /** + * @brief Uploads this number of bytes of the source blob from the offset. Null means + * upload until the end. + */ Azure::Core::Nullable SourceLength; + + /** + * @brief An MD5 hash of the blob content. This hash is used to verify the integrity of + * the blob during transport. When this header is specified, the storage service checks the hash + * that has arrived with the one that was sent. + */ Azure::Core::Nullable ContentMD5; + + /** + * @brief A CRC64 hash of the blob content. This hash is used to verify the integrity of + * the blob during transport. When this header is specified, the storage service checks the hash + * that has arrived with the one that was sent. + */ Azure::Core::Nullable ContentCRC64; + + /** + * @brief Specify this header to perform the operation only if the resource has an + * active lease mathing this id. + */ Azure::Core::Nullable LeaseId; + + /** + * @brief Ensures that the AppendBlock operation succeeds only if the append blob's size + * is less than or equal to this value. + */ Azure::Core::Nullable MaxSize; + + /** + * @brief Ensures that the AppendBlock operation succeeds only if the append position is + * equal to this value. + */ Azure::Core::Nullable AppendPosition; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for PageBlobClient::Create. + */ struct CreatePageBlobOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; Azure::Core::Nullable SequenceNumber; + + /** + * @brief The standard HTTP header system properties to set. + */ BlobHttpHeaders Properties; + + /** + * @brief Name-value pairs associated with the blob as metadata. + */ std::map Metadata; + + /** + * @brief Indicates the tier to be set on blob. + */ Azure::Core::Nullable Tier; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for PageBlobClient::UploadPages. + */ struct UploadPagesOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief An MD5 hash of the blob content. This hash is used to verify the integrity of + * the blob during transport. When this header is specified, the storage service checks the hash + * that has arrived with the one that was sent. + */ Azure::Core::Nullable ContentMD5; + + /** + * @brief A CRC64 hash of the blob content. This hash is used to verify the integrity of + * the blob during transport. When this header is specified, the storage service checks the hash + * that has arrived with the one that was sent. + */ Azure::Core::Nullable ContentCRC64; + + /** + * @brief Specify this header to perform the operation only if the resource has an + * active lease mathing this id. + */ Azure::Core::Nullable LeaseId; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for PageBlobClient::UploadPagesFromUri. + */ struct UploadPagesFromUriOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief An MD5 hash of the blob content. This hash is used to verify the integrity of + * the blob during transport. When this header is specified, the storage service checks the hash + * that has arrived with the one that was sent. + */ Azure::Core::Nullable ContentMD5; + + /** + * @brief A CRC64 hash of the blob content. This hash is used to verify the integrity of + * the blob during transport. When this header is specified, the storage service checks the hash + * that has arrived with the one that was sent. + */ Azure::Core::Nullable ContentCRC64; + + /** + * @brief Specify this header to perform the operation only if the resource has an + * active lease mathing this id. + */ Azure::Core::Nullable LeaseId; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for PageBlobClient::ClearPages. + */ struct ClearPagesOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Specify this header to perform the operation only if the resource has an + * active lease mathing this id. + */ Azure::Core::Nullable LeaseId; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for PageBlobClient::Resize. + */ struct ResizePageBlobOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for PageBlobClient::GetPageRanges. + */ struct GetPageRangesOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Specifies that the response will contain only pages that were changed between + * target blob and previous snapshot. Changed pages include both updated and cleared pages. + * The target blob may be a snapshot, as long as the snapshot specified by PreviousSnapshot is + * the older of the two. + */ Azure::Core::Nullable PreviousSnapshot; + + /** + * @brief This parameter only works with managed disk storage accounts. Specifies that + * the response will contain only pages that were changed between target blob and previous + * snapshot. Changed pages include both updated and cleared pages. The target blob may be a + * snapshot, as long as the snapshot specified by PreviousSnapshotUrl is the older of the two. + */ Azure::Core::Nullable PreviousSnapshotUrl; + + /** + * @brief Optionally specifies the offset of range over which to list ranges. + */ Azure::Core::Nullable Offset; + + /** + * @brief Optionally specifies the length of range over which to list ranges. + */ Azure::Core::Nullable Length; + + /** + * @brief Specify this header to perform the operation only if the resource has an + * active lease mathing this id. + */ Azure::Core::Nullable LeaseId; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; + /** + * @brief Optional parameters for PageBlobClient::StartCopyIncremental. + */ struct IncrementalCopyPageBlobOptions { + /** + * @brief Context for cancelling long running operations. + */ Azure::Core::Context Context; + + /** + * @brief Specify this header to perform the operation only if the resource has been + * modified since the specified time. + */ Azure::Core::Nullable IfModifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource has not been + * modified since the specified date/time. + */ Azure::Core::Nullable IfUnmodifiedSince; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag + * matches the value specified. + */ Azure::Core::Nullable IfMatch; + + /** + * @brief Specify this header to perform the operation only if the resource's ETag does + * not match the value specified. Specify the wildcard character (*) to perform the operation + * only if the resource does not exist, and fail the operation if it does exist. + */ Azure::Core::Nullable IfNoneMatch; }; diff --git a/sdk/storage/inc/blobs/block_blob_client.hpp b/sdk/storage/inc/blobs/block_blob_client.hpp index 906163268..ad4684f03 100644 --- a/sdk/storage/inc/blobs/block_blob_client.hpp +++ b/sdk/storage/inc/blobs/block_blob_client.hpp @@ -13,52 +13,166 @@ namespace Azure { namespace Storage { namespace Blobs { + /** + * @brief The BlockBlobClient allows you to manipulate Azure Storage block blobs. + * + * Block blobs let you upload large blobs efficiently. Block blobs are comprised of blocks, each + * of which is identified by a block ID. You create or modify a block blob by writing a set of + * blocks and committing them by their block IDs. Each block can be a different size. + * + * When you upload a block to a blob in your storage account, it is associated with the specified + * block blob, but it does not become part of the blob until you commit a list of blocks that + * includes the new block's ID. New blocks remain in an uncommitted state until they are + * specifically committed or discarded. Writing a block does not update the last modified time of + * an existing blob. + */ class BlockBlobClient : public BlobClient { public: - // connection string + /** + * @brief Initialize a new instance of BlockBlobClient. + * + * @param connectionString A connection string includes the authentication information required + * for your application to access data in an Azure Storage account at runtime. + * @param containerName The name of the container containing this blob. + * @param blobName The name of this blob. + * @param options Optional client options that define the transport pipeline policies for + * authentication, retries, etc., that are applied to every request. + * @return A new BlockBlobClient instance. + */ static BlockBlobClient CreateFromConnectionString( const std::string& connectionString, const std::string& containerName, const std::string& blobName, const BlockBlobClientOptions& options = BlockBlobClientOptions()); - // shared key auth + /** + * @brief Initialize a new instance of BlockBlobClient. + * + * @param blobUri A uri + * referencing the blob that includes the name of the account, the name of the container, and + * the name of the blob. + * @param credential The shared key credential used to sign + * requests. + * @param options Optional client options that define the transport pipeline + * policies for authentication, retries, etc., that are applied to every request. + */ explicit BlockBlobClient( const std::string& blobUri, std::shared_ptr credential, const BlockBlobClientOptions& options = BlockBlobClientOptions()); - // token auth + /** + * @brief Initialize a new instance of BlockBlobClient. + * + * @param blobUri A uri + * referencing the blob that includes the name of the account, the name of the container, and + * the name of the blob. + * @param credential The token credential used to sign requests. + * @param options Optional client options that define the transport pipeline policies for + * authentication, retries, etc., that are applied to every request. + */ explicit BlockBlobClient( const std::string& blobUri, std::shared_ptr credential, const BlockBlobClientOptions& options = BlockBlobClientOptions()); - // anonymous/SAS/customized pipeline auth + /** + * @brief Initialize a new instance of BlockBlobClient. + * + * @param blobUri A uri + * referencing the blob that includes the name of the account, the name of the container, and + * the name of the blob, and possibly also a SAS token. + * @param options Optional client + * options that define the transport pipeline policies for authentication, retries, etc., that + * are applied to every request. + */ explicit BlockBlobClient( const std::string& blobUri, const BlockBlobClientOptions& options = BlockBlobClientOptions()); + /** + * @brief Initializes a new instance of the BlockBlobClient class with an identical uri + * source but the specified snapshot timestamp. + * + * @param snapshot The snapshot + * identifier. + * @return A new BlockBlobClient instance. + * @remarks Pass empty string to remove the snapshot returning the base blob. + */ BlockBlobClient WithSnapshot(const std::string& snapshot) const; + /** + * @brief Creates a new block blob, or updates the content of an existing block blob. Updating + * an existing block blob overwrites any existing metadata on the blob. + * + * @param content A BodyStream containing the content to upload. + * @param options Optional parameters to execute this function. + * @return A BlobContentInfo describing the state of the updated block blob. + */ BlobContentInfo Upload( std::unique_ptr content, - const UploadBlobOptions& options = UploadBlobOptions()) const; + const UploadBlockBlobOptions& options = UploadBlockBlobOptions()) const; + /** + * @brief Creates a new block as part of a block blob's staging area to be eventually + * committed via the CommitBlockList operation. + * + * @param blockId A valid Base64 string value that identifies the block. Prior to encoding, the + * string must be less than or equal to 64 bytes in size. + * @param content A BodyStream containing the content to upload. + * @param options Optional parameters to execute this function. + * @return A BlockInfo describing the state of the updated block. + */ BlockInfo StageBlock( const std::string& blockId, std::unique_ptr content, const StageBlockOptions& options = StageBlockOptions()) const; + /** + * @brief Creates a new block to be committed as part of a blob where the contents are read from + * the sourceUri. + * + * @param blockId A valid Base64 string value that identifies the block. Prior to encoding, the + * string must be less than or equal to 64 bytes in size. + * @param sourceUri Specifies the uri of the source + * blob. The value may be a uri of up to 2 KB in length that specifies a blob. The source blob + * must either be public or must be authenticated via a shared access signature. If the source + * blob is public, no authentication is required to perform the operation. + * @param options Optional parameters to execute this function. + * @return A BlockInfo describing the state of the updated block blob. + */ BlockInfo StageBlockFromUri( const std::string& blockId, const std::string& sourceUri, const StageBlockFromUriOptions& options = StageBlockFromUriOptions()) const; + /** + * @brief Writes a blob by specifying the list of block IDs that make up the blob. In order to + * be written as part of a blob, a block must have been successfully written to the server in a + * prior StageBlock operation. You can call CommitBlockList to update a blob by uploading only + * those blocks that have changed, then committing the new and existing blocks together. You can + * do this by specifying whether to commit a block from the committed block list or from the + * uncommitted block list, or to commit the most recently uploaded version of the block, + * whichever list it may belong to. + * + * @param blockIds Base64 encoded block IDs to indicate that make up the blob. + * @param options Optional parameters to execute this function. + * @return A BlobContentInfo describing the state of the updated block blob. + */ BlobContentInfo CommitBlockList( const std::vector>& blockIds, const CommitBlockListOptions& options = CommitBlockListOptions()) const; + /** + * @brief Retrieves the list of blocks that have been uploaded as part of a block blob. There + * are two block lists maintained for a blob. The Committed Block list has blocks that have been + * successfully committed to a given blob with CommitBlockList. The Uncommitted Block list has + * blocks that have been uploaded for a blob using StageBlock, but that have not yet been + * committed. + * + * @param options Optional parameters to execute this function. + * @return A BlobBlockListInfo describing requested block list. + */ BlobBlockListInfo GetBlockList( const GetBlockListOptions& options = GetBlockListOptions()) const; diff --git a/sdk/storage/src/blobs/block_blob_client.cpp b/sdk/storage/src/blobs/block_blob_client.cpp index e6622b09c..3658a5969 100644 --- a/sdk/storage/src/blobs/block_blob_client.cpp +++ b/sdk/storage/src/blobs/block_blob_client.cpp @@ -59,7 +59,7 @@ namespace Azure { namespace Storage { namespace Blobs { BlobContentInfo BlockBlobClient::Upload( std::unique_ptr content, - const UploadBlobOptions& options) const + const UploadBlockBlobOptions& options) const { BlobRestClient::BlockBlob::UploadOptions protocolLayerOptions; protocolLayerOptions.BodyStream = std::move(content); diff --git a/sdk/storage/test/block_blob_client_test.cpp b/sdk/storage/test/block_blob_client_test.cpp index b3a572ccf..ab1f83ee3 100644 --- a/sdk/storage/test/block_blob_client_test.cpp +++ b/sdk/storage/test/block_blob_client_test.cpp @@ -22,7 +22,7 @@ namespace Azure { namespace Storage { namespace Test { std::shared_ptr BlockBlobClientTest::m_blockBlobClient; std::string BlockBlobClientTest::m_blobName; - Azure::Storage::Blobs::UploadBlobOptions BlockBlobClientTest::m_blobUploadOptions; + Azure::Storage::Blobs::UploadBlockBlobOptions BlockBlobClientTest::m_blobUploadOptions; std::vector BlockBlobClientTest::m_blobContent; void BlockBlobClientTest::SetUpTestSuite() diff --git a/sdk/storage/test/block_blob_client_test.hpp b/sdk/storage/test/block_blob_client_test.hpp index 54d06e364..139ab0dd4 100644 --- a/sdk/storage/test/block_blob_client_test.hpp +++ b/sdk/storage/test/block_blob_client_test.hpp @@ -14,7 +14,7 @@ namespace Azure { namespace Storage { namespace Test { static std::shared_ptr m_blockBlobClient; static std::string m_blobName; - static Azure::Storage::Blobs::UploadBlobOptions m_blobUploadOptions; + static Azure::Storage::Blobs::UploadBlockBlobOptions m_blobUploadOptions; static std::vector m_blobContent; };