azure-storage
Version:
Microsoft Azure Storage Client Library for Node.js
755 lines (662 loc) • 260 kB
JavaScript
//
// Copyright (c) Microsoft and contributors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//
// See the License for the specific language governing permissions and
// limitations under the License.
//
// Module dependencies.
var qs = require('querystring');
var url = require('url');
var util = require('util');
var _ = require('underscore');
var extend = require('extend');
var path = require('path');
var azureCommon = require('./../../common/common.core');
var Md5Wrapper = require('./../../common/md5-wrapper');
var azureutil = azureCommon.util;
var SR = azureCommon.SR;
var validate = azureCommon.validate;
var SpeedSummary = azureCommon.SpeedSummary;
var StorageServiceClient = azureCommon.StorageServiceClient;
var WebResource = azureCommon.WebResource;
// Constants
var Constants = azureCommon.Constants;
var FileConstants = Constants.FileConstants;
var HeaderConstants = Constants.HeaderConstants;
var HttpConstants = Constants.HttpConstants;
var QueryStringConstants = Constants.QueryStringConstants;
// Streams
var BatchOperation = azureCommon.BatchOperation;
var SpeedSummary = azureCommon.SpeedSummary;
var ChunkAllocator = azureCommon.ChunkAllocator;
var ChunkStream = azureCommon.ChunkStream;
var ChunkStreamWithStream = azureCommon.ChunkStreamWithStream;
var FileRangeStream = require('./internal/filerangestream');
// Models requires
var ShareResult = require('./models/shareresult');
var DirectoryResult = require('./models/directoryresult');
var FileResult = require('./models/fileresult');
var AclResult = azureCommon.AclResult;
// Errors requires
var errors = require('../../common/errors/errors');
var ArgumentNullError = errors.ArgumentNullError;
var ArgumentError = errors.ArgumentError;
/**
* Creates a new FileService object.
* If no connection string or storageaccount and storageaccesskey are provided,
* the AZURE_STORAGE_CONNECTION_STRING or AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_ACCESS_KEY environment variables will be used.
* @class
* The FileService class is used to perform operations on the Microsoft Azure File Service.
* The File Service provides storage for binary large objects, and provides functions for working with data stored in files.
*
* For more information on the File Service, as well as task focused information on using it in a Node.js application, see
* [How to Use the File Service from Node.js](http://azure.microsoft.com/en-us/documentation/articles/storage-nodejs-how-to-use-file-storage/).
* The following defaults can be set on the file service.
* defaultTimeoutIntervalInMs The default timeout interval, in milliseconds, to use for request made via the file service.
* defaultEnableReuseSocket The default boolean value to enable socket reuse when uploading local files or streams.
* If the Node.js version is lower than 0.10.x, socket reuse will always be turned off.
* defaultClientRequestTimeoutInMs The default timeout of client requests, in milliseconds, to use for the request made via the file service.
* defaultMaximumExecutionTimeInMs The default maximum execution time across all potential retries, for requests made via the file service.
* defaultLocationMode The default location mode for requests made via the file service.
* parallelOperationThreadCount The number of parallel operations that may be performed when uploading a file.
* useNagleAlgorithm Determines whether the Nagle algorithm is used for requests made via the file service; true to use the
* Nagle algorithm; otherwise, false. The default value is false.
* enableGlobalHttpAgent Determines whether global HTTP(s) agent is enabled; true to use Global HTTP(s) agent; otherwise, false to use
* http(s).Agent({keepAlive:true}).
* @constructor
* @extends {StorageServiceClient}
*
* @param {string} [storageAccountOrConnectionString] The storage account or the connection string.
* @param {string} [storageAccessKey] The storage access key.
* @param {string|object} [host] The host address. To define primary only, pass a string.
* Otherwise 'host.primaryHost' defines the primary host and 'host.secondaryHost' defines the secondary host.
* @param {string} [sasToken] The Shared Access Signature token.
* @param {string} [endpointSuffix] The endpoint suffix.
*/
function FileService(storageAccountOrConnectionString, storageAccessKey, host, sasToken, endpointSuffix) {
var storageServiceSettings = StorageServiceClient.getStorageSettings(storageAccountOrConnectionString, storageAccessKey, host, sasToken, endpointSuffix);
FileService['super_'].call(this,
storageServiceSettings._name,
storageServiceSettings._key,
storageServiceSettings._fileEndpoint,
storageServiceSettings._usePathStyleUri,
storageServiceSettings._sasToken);
this.defaultEnableReuseSocket = Constants.DEFAULT_ENABLE_REUSE_SOCKET;
this.singleFileThresholdInBytes = FileConstants.DEFAULT_SINGLE_FILE_GET_THRESHOLD_IN_BYTES;
this.parallelOperationThreadCount = Constants.DEFAULT_PARALLEL_OPERATION_THREAD_COUNT;
}
util.inherits(FileService, StorageServiceClient);
// Utility methods
/**
* Create resource name
* @ignore
*
* @param {string} share Share name
* @param {string} [directory] Directory name
* @param {string} [file] File name
* @return {string} The encoded resource name.
*/
function createResourceName(share, directory, file, forSAS) {
var encode = function(name) {
if (name && !forSAS) {
name = encodeURIComponent(name);
name = name.replace(/%2F/g, '/');
name = name.replace(/%5C/g, '/');
name = name.replace(/\+/g, '%20');
}
return name;
};
var name = share;
if (directory) {
// if directory does not start with '/', add it
if (directory[0] !== '/') {
name += ('/');
}
name += encode(directory);
}
if (file) {
// if the current path does not end with '/', add it
if (name[name.length - 1] !== '/') {
name += ('/');
}
name += encode(file);
}
return path.normalize(name).replace(/\\/g, '/');
}
// File service methods
/**
* Gets the properties of a storage account's File service, including Azure Storage Analytics.
*
* @this {FileService}
* @param {object} [options] The request options.
* @param {LocationMode} [options.locationMode] Specifies the location mode used to decide which location the request should be sent to.
* Please see StorageUtilities.LocationMode for the possible values.
* @param {int} [options.timeoutIntervalInMs] The server timeout interval, in milliseconds, to use for the request.
* @param {int} [options.clientRequestTimeoutInMs] The timeout of client requests, in milliseconds, to use for the request.
* @param {int} [options.maximumExecutionTimeInMs] The maximum execution time, in milliseconds, across all potential retries, to use when making this request.
* The maximum execution time interval begins at the time that the client begins building the request. The maximum
* execution time is checked intermittently while performing requests, and before executing retries.
* @param {string} [options.clientRequestId] A string that represents the client request ID with a 1KB character limit.
* @param {bool} [options.useNagleAlgorithm] Determines whether the Nagle algorithm is used; true to use the Nagle algorithm; otherwise, false.
* The default value is false.
* @param {errorOrResult} callback `error` will contain information if an error occurs; otherwise, `[result]{@link ServiceProperties}` will contain the properties
* and `response` will contain information related to this operation.
*/
FileService.prototype.getServiceProperties = function (optionsOrCallback, callback) {
return this.getAccountServiceProperties(optionsOrCallback, callback);
};
/**
* Sets the properties of a storage account's File service, including Azure Storage Analytics.
* You can also use this operation to set the default request version for all incoming requests that do not have a version specified.
*
* @this {FileService}
* @param {object} serviceProperties The service properties.
* @param {object} [options] The request options.
* @param {LocationMode} [options.locationMode] Specifies the location mode used to decide which location the request should be sent to.
* Please see StorageUtilities.LocationMode for the possible values.
* @param {int} [options.timeoutIntervalInMs] The server timeout interval, in milliseconds, to use for the request.
* @param {int} [options.clientRequestTimeoutInMs] The timeout of client requests, in milliseconds, to use for the request.
* @param {int} [options.maximumExecutionTimeInMs] The maximum execution time, in milliseconds, across all potential retries, to use when making this request.
* The maximum execution time interval begins at the time that the client begins building the request. The maximum
* execution time is checked intermittently while performing requests, and before executing retries.
* @param {string} [options.clientRequestId] A string that represents the client request ID with a 1KB character limit.
* @param {bool} [options.useNagleAlgorithm] Determines whether the Nagle algorithm is used; true to use the Nagle algorithm; otherwise, false.
* The default value is false.
* @param {errorOrResponse} callback `error` will contain information
* if an error occurs; otherwise, `response`
* will contain information related to this operation.
*/
FileService.prototype.setServiceProperties = function (serviceProperties, optionsOrCallback, callback) {
return this.setAccountServiceProperties(serviceProperties, optionsOrCallback, callback);
};
// Share methods
/**
* Lists a segment containing a collection of share items under the specified account.
*
* @this {FileService}
* @param {object} currentToken A continuation token returned by a previous listing operation. Please use 'null' or 'undefined' if this is the first operation.
* @param {object} [options] The request options.
* @param {LocationMode} [options.locationMode] Specifies the location mode used to decide which location the request should be sent to.
* Please see StorageUtilities.LocationMode for the possible values.
* @param {int} [options.maxResults] Specifies the maximum number of shares to return per call to Azure storage.
* @param {string} [options.include] Include this parameter to specify that the share's metadata be returned as part of the response body. (allowed values: '', 'metadata', 'snapshots' or any combination of them)
* **Note** that all metadata names returned from the server will be converted to lower case by NodeJS itself as metadata is set via HTTP headers and HTTP header names are case insensitive.
* @param {int} [options.timeoutIntervalInMs] The server timeout interval, in milliseconds, to use for the request.
* @param {int} [options.clientRequestTimeoutInMs] The timeout of client requests, in milliseconds, to use for the request.
* @param {int} [options.maximumExecutionTimeInMs] The maximum execution time, in milliseconds, across all potential retries, to use when making this request.
* The maximum execution time interval begins at the time that the client begins building the request. The maximum
* execution time is checked intermittently while performing requests, and before executing retries.
* @param {string} [options.clientRequestId] A string that represents the client request ID with a 1KB character limit.
* @param {bool} [options.useNagleAlgorithm] Determines whether the Nagle algorithm is used; true to use the Nagle algorithm; otherwise, false.
* The default value is false.
* @param {errorOrResult} callback `error` will contain information
* if an error occurs; otherwise `result` will contain `entries` and `continuationToken`.
* `entries` gives a list of `[shares]{@link ShareResult}` and the `continuationToken` is used for the next listing operation.
* `response` will contain information related to this operation.
*/
FileService.prototype.listSharesSegmented = function (currentToken, optionsOrCallback, callback) {
this.listSharesSegmentedWithPrefix(null /* prefix */, currentToken, optionsOrCallback, callback);
};
/**
* Lists a segment containing a collection of share items whose names begin with the specified prefix under the specified account.
*
* @this {FileService}
* @param {string} prefix The prefix of the share name.
* @param {object} currentToken A continuation token returned by a previous listing operation. Please use 'null' or 'undefined' if this is the first operation.
* @param {object} [options] The request options.
* @param {LocationMode} [options.locationMode] Specifies the location mode used to decide which location the request should be sent to.
* Please see StorageUtilities.LocationMode for the possible values.
* @param {string} [options.prefix] Filters the results to return only shares whose name begins with the specified prefix.
* @param {int} [options.maxResults] Specifies the maximum number of shares to return per call to Azure storage.
* @param {string} [options.include] Include this parameter to specify that the share's metadata be returned as part of the response body. (allowed values: '', 'metadata', 'snapshots' or any combination of them)
* **Note** that all metadata names returned from the server will be converted to lower case by NodeJS itself as metadata is set via HTTP headers and HTTP header names are case insensitive.
* @param {int} [options.timeoutIntervalInMs] The server timeout interval, in milliseconds, to use for the request.
* @param {int} [options.clientRequestTimeoutInMs] The timeout of client requests, in milliseconds, to use for the request.
* @param {int} [options.maximumExecutionTimeInMs] The maximum execution time, in milliseconds, across all potential retries, to use when making this request.
* The maximum execution time interval begins at the time that the client begins building the request. The maximum
* execution time is checked intermittently while performing requests, and before executing retries.
* @param {string} [options.clientRequestId] A string that represents the client request ID with a 1KB character limit.
* @param {bool} [options.useNagleAlgorithm] Determines whether the Nagle algorithm is used; true to use the Nagle algorithm; otherwise, false.
* The default value is false.
* @param {errorOrResult} callback `error` will contain information
* if an error occurs; otherwise `result` will contain `entries` and `continuationToken`.
* `entries` gives a list of `[shares]{@link ShareResult}` and the `continuationToken` is used for the next listing operation.
* `response` will contain information related to this operation.
*/
FileService.prototype.listSharesSegmentedWithPrefix = function (prefix, currentToken, optionsOrCallback, callback) {
var userOptions;
azureutil.normalizeArgs(optionsOrCallback, callback, function (o, c) { userOptions = o; callback = c; });
validate.validateArgs('listShares', function (v) {
v.callback(callback);
});
var options = extend(true, {}, userOptions);
var webResource = WebResource.get()
.withQueryOption(QueryStringConstants.COMP, 'list')
.withQueryOption(QueryStringConstants.MAX_RESULTS, options.maxResults)
.withQueryOption(QueryStringConstants.INCLUDE, options.include);
if (!azureutil.objectIsNull(currentToken)) {
webResource.withQueryOption(QueryStringConstants.MARKER, currentToken.nextMarker);
}
webResource.withQueryOption(QueryStringConstants.PREFIX, prefix);
//options.requestLocationMode = azureutil.getNextListingLocationMode(currentToken);
var processResponseCallback = function (responseObject, next) {
responseObject.listSharesResult = null;
if (!responseObject.error) {
responseObject.listSharesResult = {
entries: null,
continuationToken: null
};
responseObject.listSharesResult.entries = [];
var shares = [];
if (responseObject.response.body.EnumerationResults.Shares && responseObject.response.body.EnumerationResults.Shares.Share) {
shares = responseObject.response.body.EnumerationResults.Shares.Share;
if (!_.isArray(shares)) {
shares = [shares];
}
}
shares.forEach(function (currentShare) {
var shareResult = ShareResult.parse(currentShare);
responseObject.listSharesResult.entries.push(shareResult);
});
if (responseObject.response.body.EnumerationResults.NextMarker) {
responseObject.listSharesResult.continuationToken = {
nextMarker: null,
targetLocation: null
};
responseObject.listSharesResult.continuationToken.nextMarker = responseObject.response.body.EnumerationResults.NextMarker;
responseObject.listSharesResult.continuationToken.targetLocation = responseObject.targetLocation;
}
}
var finalCallback = function (returnObject) {
callback(returnObject.error, returnObject.listSharesResult, returnObject.response);
};
next(responseObject, finalCallback);
};
this.performRequest(webResource, null, options, processResponseCallback);
};
/**
* Checks whether or not a share exists on the service.
*
* @this {FileService}
* @param {string} share The share name.
* @param {object} [options] The request options.
* @param {string} [options.shareSnapshotId] The snapshot identifier of the share.
* @param {LocationMode} [options.locationMode] Specifies the location mode used to decide which location the request should be sent to.
* Please see StorageUtilities.LocationMode for the possible values.
* @param {int} [options.timeoutIntervalInMs] The server timeout interval, in milliseconds, to use for the request.
* @param {int} [options.clientRequestTimeoutInMs] The timeout of client requests, in milliseconds, to use for the request.
* @param {int} [options.maximumExecutionTimeInMs] The maximum execution time, in milliseconds, across all potential retries, to use when making this request.
* The maximum execution time interval begins at the time that the client begins building the request. The maximum
* execution time is checked intermittently while performing requests, and before executing retries.
* @param {string} [options.clientRequestId] A string that represents the client request ID with a 1KB character limit.
* @param {bool} [options.useNagleAlgorithm] Determines whether the Nagle algorithm is used; true to use the Nagle algorithm; otherwise, false.
* The default value is false.
* @param {errorOrResult} callback `error` will contain information
* if an error occurs; otherwise `[result]{@link ShareResult}` will contain
* the share information including `exists` boolean member.
* `response` will contain information related to this operation.
*/
FileService.prototype.doesShareExist = function (share, optionsOrCallback, callback) {
this._doesShareExist(share, false, optionsOrCallback, callback);
};
/**
* Creates a new share under the specified account.
* If a share with the same name already exists, the operation fails.
*
* @this {FileService}
* @param {string} share The share name.
* @param {object} [options] The request options.
* @param {int} [options.quota] Specifies the maximum size of the share, in gigabytes.
* @param {LocationMode} [options.locationMode] Specifies the location mode used to decide which location the request should be sent to.
* Please see StorageUtilities.LocationMode for the possible values.
* @param {object} [options.metadata] The metadata key/value pairs.
* @param {int} [options.timeoutIntervalInMs] The server timeout interval, in milliseconds, to use for the request.
* @param {int} [options.clientRequestTimeoutInMs] The timeout of client requests, in milliseconds, to use for the request.
* @param {int} [options.maximumExecutionTimeInMs] The maximum execution time, in milliseconds, across all potential retries, to use when making this request.
* The maximum execution time interval begins at the time that the client begins building the request. The maximum
* execution time is checked intermittently while performing requests, and before executing retries.
* @param {string} [options.clientRequestId] A string that represents the client request ID with a 1KB character limit.
* @param {bool} [options.useNagleAlgorithm] Determines whether the Nagle algorithm is used; true to use the Nagle algorithm; otherwise, false.
* The default value is false.
* @param {errorOrResult} callback `error` will contain information
* if an error occurs; otherwise `[result]{@link ShareResult}` will contain
* the share information.
* `response` will contain information related to this operation.
*/
FileService.prototype.createShare = function (share, optionsOrCallback, callback) {
var userOptions;
azureutil.normalizeArgs(optionsOrCallback, callback, function (o, c) { userOptions = o; callback = c; });
validate.validateArgs('createShare', function (v) {
v.string(share, 'share');
v.shareNameIsValid(share);
v.shareQuotaIsValid(userOptions.quota);
v.callback(callback);
});
var options = extend(true, {}, userOptions);
var webResource = WebResource.put(share)
.withQueryOption(QueryStringConstants.RESTYPE, 'share')
.withHeader(HeaderConstants.SHARE_QUOTA, options.quota);
webResource.addOptionalMetadataHeaders(options.metadata);
var processResponseCallback = function (responseObject, next) {
responseObject.shareResult = null;
if (!responseObject.error) {
responseObject.shareResult = new ShareResult(share);
responseObject.shareResult.getPropertiesFromHeaders(responseObject.response.headers);
if (options.metadata) {
responseObject.shareResult.metadata = options.metadata;
}
}
var finalCallback = function (returnObject) {
callback(returnObject.error, returnObject.shareResult, returnObject.response);
};
next(responseObject, finalCallback);
};
this.performRequest(webResource, null, options, processResponseCallback);
};
/**
* Creates a share snapshot.
*
* @this {FileService}
* @param {string} share The share name.
* @param {object} [options] The request options.
* @param {LocationMode} [options.locationMode] Specifies the location mode used to decide which location the request should be sent to.
* Please see StorageUtilities.LocationMode for the possible values.
* @param {object} [options.metadata] The metadata key/value pairs.
* @param {int} [options.timeoutIntervalInMs] The server timeout interval, in milliseconds, to use for the request.
* @param {int} [options.clientRequestTimeoutInMs] The timeout of client requests, in milliseconds, to use for the request.
* @param {int} [options.maximumExecutionTimeInMs] The maximum execution time, in milliseconds, across all potential retries, to use when making this request.
* The maximum execution time interval begins at the time that the client begins building the request. The maximum
* execution time is checked intermittently while performing requests, and before executing retries.
* @param {string} [options.clientRequestId] A string that represents the client request ID with a 1KB character limit.
* @param {bool} [options.useNagleAlgorithm] Determines whether the Nagle algorithm is used; true to use the Nagle algorithm; otherwise, false.
* The default value is false.
* @param {errorOrResult} callback `error` will contain information
* if an error occurs; otherwise `result` will contain
* the ID of the snapshot.
* `response` will contain information related to this operation.
*/
FileService.prototype.createShareSnapshot = function (share, optionsOrCallback, callback) {
var userOptions;
azureutil.normalizeArgs(optionsOrCallback, callback, function (o, c) { userOptions = o; callback = c; });
validate.validateArgs('createShareSnapshot', function (v) {
v.string(share, 'share');
v.shareNameIsValid(share);
v.callback(callback);
});
var options = extend(true, {}, userOptions);
var webResource = WebResource.put(share)
.withQueryOption(QueryStringConstants.RESTYPE, 'share')
.withQueryOption(QueryStringConstants.COMP, QueryStringConstants.SNAPSHOT);
webResource.addOptionalMetadataHeaders(options.metadata);
var processResponseCallback = function (responseObject, next) {
responseObject.snapshotId = null;
if (!responseObject.error) {
responseObject.snapshotId = responseObject.response.headers[HeaderConstants.SNAPSHOT];
}
var finalCallback = function (returnObject) {
callback(returnObject.error, returnObject.snapshotId, returnObject.response);
};
next(responseObject, finalCallback);
};
this.performRequest(webResource, null, options, processResponseCallback);
};
/**
* Creates a new share under the specified account if the share does not exists.
*
* @this {FileService}
* @param {string} share The share name.
* @param {object} [options] The request options.
* @param {LocationMode} [options.locationMode] Specifies the location mode used to decide which location the request should be sent to.
* Please see StorageUtilities.LocationMode for the possible values.
* @param {object} [options.metadata] The metadata key/value pairs.
* @param {int} [options.timeoutIntervalInMs] The server timeout interval, in milliseconds, to use for the request.
* @param {int} [options.clientRequestTimeoutInMs] The timeout of client requests, in milliseconds, to use for the request.
* @param {int} [options.maximumExecutionTimeInMs] The maximum execution time, in milliseconds, across all potential retries, to use when making this request.
* The maximum execution time interval begins at the time that the client begins building the request. The maximum
* execution time is checked intermittently while performing requests, and before executing retries.
* @param {string} [options.clientRequestId] A string that represents the client request ID with a 1KB character limit.
* @param {bool} [options.useNagleAlgorithm] Determines whether the Nagle algorithm is used; true to use the Nagle algorithm; otherwise, false.
* The default value is false.
* @param {errorOrResult} callback `error` will contain information
* if an error occurs; otherwise `[result]{@link ShareResult}` will contain
* the share information including `created` boolean member.
* `response` will contain information related to this operation.
*
* @example
* var azure = require('azure-storage');
* var FileService = azure.createFileService();
* FileService.createShareIfNotExists('taskshare', function(error) {
* if(!error) {
* // Share created or already existed
* }
* });
*/
FileService.prototype.createShareIfNotExists = function (share, optionsOrCallback, callback) {
var userOptions;
azureutil.normalizeArgs(optionsOrCallback, callback, function (o, c) { userOptions = o; callback = c; });
validate.validateArgs('createShareIfNotExists', function (v) {
v.string(share, 'share');
v.shareNameIsValid(share);
v.callback(callback);
});
var options = extend(true, {}, userOptions);
delete options.shareSnapshotId;
var self = this;
self._doesShareExist(share, true, options, function(error, result, response) {
var exists = result.exists;
result.created = false;
delete result.exists;
if(error){
callback(error, result, response);
} else if (exists) {
response.isSuccessful = true;
callback(error, result, response);
} else {
self.createShare(share, options, function (createError, responseShare, createResponse) {
if(!createError){
responseShare.created = true;
}
else if (createError && createError.statusCode === HttpConstants.HttpResponseCodes.Conflict && createError.code === Constants.FileErrorCodeStrings.SHARE_ALREADY_EXISTS) {
// If it was created before, there was no actual error.
createError = null;
createResponse.isSuccessful = true;
}
callback(createError, responseShare, createResponse);
});
}
});
};
/**
* Retrieves a share and its properties from a specified account.
* **Note** that all metadata names returned from the server will be converted to lower case by NodeJS itself as metadata is set via HTTP headers and HTTP header names are case insensitive.
*
* @this {FileService}
* @param {string} share The share name.
* @param {object} [options] The request options.
* @param {string} [options.shareSnapshotId] The snapshot identifier of the share.
* @param {LocationMode} [options.locationMode] Specifies the location mode used to decide which location the request should be sent to.
* Please see StorageUtilities.LocationMode for the possible values.
* @param {int} [options.timeoutIntervalInMs] The server timeout interval, in milliseconds, to use for the request.
* @param {int} [options.clientRequestTimeoutInMs] The timeout of client requests, in milliseconds, to use for the request.
* @param {int} [options.maximumExecutionTimeInMs] The maximum execution time, in milliseconds, across all potential retries, to use when making this request.
* The maximum execution time interval begins at the time that the client begins building the request. The maximum
* execution time is checked intermittently while performing requests, and before executing retries.
* @param {string} [options.clientRequestId] A string that represents the client request ID with a 1KB character limit.
* @param {bool} [options.useNagleAlgorithm] Determines whether the Nagle algorithm is used; true to use the Nagle algorithm; otherwise, false.
* The default value is false.
* @param {errorOrResult} callback `error` will contain information
* if an error occurs; otherwise `[result]{@link ShareResult}` will contain
* information for the share.
* `response` will contain information related to this operation.
*/
FileService.prototype.getShareProperties = function (share, optionsOrCallback, callback) {
var userOptions;
azureutil.normalizeArgs(optionsOrCallback, callback, function (o, c) { userOptions = o; callback = c; });
validate.validateArgs('getShareProperties', function (v) {
v.string(share, 'share');
v.shareNameIsValid(share);
v.callback(callback);
});
var options = extend(true, {}, userOptions);
var webResource = WebResource.head(share)
.withQueryOption(QueryStringConstants.RESTYPE, 'share')
.withQueryOption(QueryStringConstants.SHARE_SNAPSHOT, options.shareSnapshotId);
//options.requestLocationMode = Constants.RequestLocationMode.PRIMARY_OR_SECONDARY;
var self = this;
var processResponseCallback = function (responseObject, next) {
responseObject.shareResult = null;
if (!responseObject.error) {
responseObject.shareResult = new ShareResult(share);
responseObject.shareResult.metadata = self.parseMetadataHeaders(responseObject.response.headers);
responseObject.shareResult.getPropertiesFromHeaders(responseObject.response.headers);
}
var finalCallback = function (returnObject) {
callback(returnObject.error, returnObject.shareResult, returnObject.response);
};
next(responseObject, finalCallback);
};
this.performRequest(webResource, null, options, processResponseCallback);
};
/**
* Sets the properties for the specified share.
*
* @this {FileService}
* @param {string} share The share name.
* @param {object} [properties] The share properties to set.
* @param {string|int} [properties.quota] Specifies the maximum size of the share, in gigabytes.
* @param {object} [options] The request options.
* @param {int} [options.timeoutIntervalInMs] The server timeout interval, in milliseconds, to use for the request.
* @param {int} [options.clientRequestTimeoutInMs] The timeout of client requests, in milliseconds, to use for the request.
* @param {int} [options.maximumExecutionTimeInMs] The maximum execution time, in milliseconds, across all potential retries, to use when making this request.
* The maximum execution time interval begins at the time that the client begins building the request. The maximum
* execution time is checked intermittently while performing requests, and before executing retries.
* @param {string} [options.clientRequestId] A string that represents the client request ID with a 1KB character limit.
* @param {bool} [options.useNagleAlgorithm] Determines whether the Nagle algorithm is used; true to use the Nagle algorithm; otherwise, false.
* The default value is false.
* @param {errorOrResult} callback `error` will contain information
* if an error occurs; otherwise `[share]{@link ShareResult}` will contain
* information about the share.
* `response` will contain information related to this operation.
*/
FileService.prototype.setShareProperties = function (share, properties, optionsOrCallback, callback) {
var userOptions;
azureutil.normalizeArgs(optionsOrCallback, callback, function (o, c) { userOptions = o; callback = c; });
validate.validateArgs('setShareProperties', function (v) {
v.string(share, 'share');
v.shareNameIsValid(share);
v.shareQuotaIsValid(userOptions.quota);
v.callback(callback);
});
var options = extend(true, properties, userOptions);
var resourceName = createResourceName(share);
var webResource = WebResource.put(resourceName)
.withQueryOption(QueryStringConstants.RESTYPE, 'share')
.withQueryOption(QueryStringConstants.COMP, 'properties')
.withHeader(HeaderConstants.SHARE_QUOTA, options.quota);
FileResult.setProperties(webResource, options);
var processResponseCallback = function (responseObject, next) {
responseObject.shareResult = null;
if (!responseObject.error) {
responseObject.shareResult = new ShareResult(share);
responseObject.shareResult.getPropertiesFromHeaders(responseObject.response.headers);
}
var finalCallback = function (returnObject) {
callback(returnObject.error, returnObject.shareResult, returnObject.response);
};
next(responseObject, finalCallback);
};
this.performRequest(webResource, null, options, processResponseCallback);
};
/**
* Gets the share statistics for a share.
*
* @this {FileService}
* @param {string} share The share name.
* @param {object} [options] The request options.
* @param {LocationMode} [options.locationMode] Specifies the location mode used to decide which location the request should be sent to.
* Please see StorageUtilities.LocationMode for the possible values.
* @param {int} [options.timeoutIntervalInMs] The timeout interval, in milliseconds, to use for the request.
* @param {int} [options.clientRequestTimeoutInMs] The timeout of client requests, in milliseconds, to use for the request.
* @param {int} [options.maximumExecutionTimeInMs] The maximum execution time, in milliseconds, across all potential retries, to use when making this request.
* The maximum execution time interval begins at the time that the client begins building the request. The maximum
* execution time is checked intermittently while performing requests, and before executing retries.
* @param {string} [options.clientRequestId] A string that represents the client request ID with a 1KB character limit.
* @param {bool} [options.useNagleAlgorithm] Determines whether the Nagle algorithm is used; true to use the Nagle algorithm; otherwise, false.
* The default value is false.
* @param {errorOrResult} callback `error` will contain information if an error occurs; otherwise, `[result]{@link ServiceStats}` will contain the stats and
* `response` will contain information related to this operation.
*/
FileService.prototype.getShareStats = function (share, optionsOrCallback, callback) {
var userOptions;
azureutil.normalizeArgs(optionsOrCallback, callback, function (o, c) { userOptions = o; callback = c; });
validate.validateArgs('getShareStats', function (v) {
v.callback(callback);
});
var options = extend(true, {}, userOptions);
var resourceName = createResourceName(share);
var webResource = WebResource.get(resourceName)
.withQueryOption(QueryStringConstants.RESTYPE, 'share')
.withQueryOption(QueryStringConstants.COMP, 'stats');
var processResponseCallback = function (responseObject, next) {
responseObject.shareResult = null;
if (!responseObject.error) {
responseObject.shareResult = ShareResult.parse(responseObject.response.body, share);
responseObject.shareResult.getPropertiesFromHeaders(responseObject.response.headers);
}
// function to be called after all filters
var finalCallback = function (returnObject) {
callback(returnObject.error, returnObject.shareResult, returnObject.response);
};
// call the first filter
next(responseObject, finalCallback);
};
this.performRequest(webResource, null, options, processResponseCallback);
};
/**
* Returns all user-defined metadata for the share.
* **Note** that all metadata names returned from the server will be converted to lower case by NodeJS itself as metadata is set via HTTP headers and HTTP header names are case insensitive.
*
* @this {FileService}
* @param {string} share The share name.
* @param {object} [options] The request options.
* @param {string} [options.shareSnapshotId] The snapshot identifier of the share.
* @param {LocationMode} [options.locationMode] Specifies the location mode used to decide which location the request should be sent to.
* Please see StorageUtilities.LocationMode for the possible values.
* @param {int} [options.timeoutIntervalInMs] The server timeout interval, in milliseconds, to use for the request.
* @param {int} [options.clientRequestTimeoutInMs] The timeout of client requests, in milliseconds, to use for the request.
* @param {int} [options.maximumExecutionTimeInMs] The maximum execution time, in milliseconds, across all potential retries, to use when making this request.
* The maximum execution time interval begins at the time that the client begins building the request. The maximum
* execution time is checked intermittently while performing requests, and before executing retries.
* @param {string} [options.clientRequestId] A string that represents the client request ID with a 1KB character limit.
* @param {bool} [options.useNagleAlgorithm] Determines whether the Nagle algorithm is used; true to use the Nagle algorithm; otherwise, false.
* The default value is false.
* @param {errorOrResult} callback `error` will contain information
* if an error occurs; otherwise `[result]{@link ShareResult}` will contain
* information for the share.
* `response` will contain information related to this operation.
*/
FileService.prototype.getShareMetadata = function (share, optionsOrCallback, callback) {
var userOptions;
azureutil.normalizeArgs(optionsOrCallback, callback, function (o, c) { userOptions = o; callback = c; });
validate.validateArgs('getShareMetadata', function (v) {
v.string(share, 'share');
v.shareNameIsValid(share);
v.callback(callback);
});
var options = extend(true, {}, userOptions);
var webResource = WebResource.head(share)
.withQueryOption(QueryStringConstants.RESTYPE, 'share')
.withQueryOption(QueryStringConstants.COMP, 'metadata')
.withQueryOption(QueryStringConstants.SHARE_SNAPSHOT, options.shareSnapshotId);
var self = this;
var processResponseCallback = function (responseObject, next) {
responseObject.shareResult = null;