mongoose 5.4.0 → 5.4.4

package/History.md

@@ -1,3 +1,44 @@
+5.4.4 / 2019-01-14
+==================
+ * fix(query): run casting on arrayFilters option #7079
+ * fix(document): support skipping timestamps on save() with `save({ timestamps: false })` #7357
+ * fix(model): apply custom where on `Document#remove()` so we attach the shardKey #7393
+ * docs(mongoose): document `mongoose.connections` #7338
+
+5.4.3 / 2019-01-09
+==================
+ * fix(populate): handle `count` option when using `Document#populate()` on a virtual #7380
+ * fix(connection): set connection state to DISCONNECTED if replica set has no primary #7330
+ * fix(mongoose): apply global plugins to schemas nested underneath embedded discriminators #7370
+ * fix(document): make modifiedPaths() return nested paths 1 level down on initial set #7313
+ * fix(plugins): ensure sharding plugin works even if ObjectId has a `valueOf()` #7353
+
+5.4.2 / 2019-01-03
+==================
+ * fix(document): ensure Document#updateOne() returns a query but still calls hooks #7366
+ * fix(query): allow explicitly projecting out populated paths that are automatically projected in #7383
+ * fix(document): support setting `flattenMaps` option for `toObject()` and `toJSON()` at schema level #7274
+ * fix(query): handle merging objectids with `.where()` #7360
+ * fix(schema): copy `.base` when cloning #7377
+ * docs: remove links to plugins.mongoosejs.com in favor of plugins.mongoosejs.io #7364
+
+5.4.1 / 2018-12-26
+==================
+ * fix(document): ensure doc array defaults get casted #7337
+ * fix(document): make `save()` not crash if nested doc has a property 'get' #7316
+ * fix(schema): allow using Schema.Types.Map as well as Map to declare a map type #7305
+ * fix(map): make set after init mark correct path as modified #7321
+ * fix(mongoose): don't recompile model if same collection and schema passed in to `mongoose.model()` #5767
+ * fix(schema): improve error message when type is invalid #7303
+ * fix(schema): add `populated` to reserved property names #7317
+ * fix(model): don't run built-in middleware on custom methods and ensure timestamp hooks don't run if children don't have timestamps set #7342
+ * docs(schematypes): clarify that you can add arbitrary options to a SchemaType #7340
+ * docs(mongoose): clarify that passing same name+schema to `mongoose.model()` returns the model #5767
+ * docs(index): add useNewUrlParser to example #7368 [JIBIN-P](https://github.com/JIBIN-P)
+ * docs(connection): add useNewUrlParser to examples #7362 [JIBIN-P](https://github.com/JIBIN-P)
+ * docs(discriminators): add back missing example from 'recursive embedded discriminators section' #7349
+ * docs(schema): improve docs for string and boolean cast() #7351
+
 5.4.0 / 2018-12-14
 ==================
  * feat(schematype): add `SchemaType.get()`, custom getters across all instances of a schematype #6912

package/lib/cast.js

@@ -7,7 +7,7 @@
 const StrictModeError = require('./error/strict');
 const Types = require('./schema/index');
 const castTextSearch = require('./schema/operators/text');
-const get = require('lodash.get');
+const get = require('./helpers/get');
 const util = require('util');
 const utils = require('./utils');
 
@@ -82,6 +82,7 @@ module.exports = function cast(schema, obj, options, context) {
           const pathLastHalf = split.slice(j).join('.');
           const _schematype = schema.path(pathFirstHalf);
           const discriminatorKey = get(_schematype, 'schema.options.discriminatorKey');
+
           // gh-6027: if we haven't found the schematype but this path is
           // underneath an embedded discriminator and the embedded discriminator
           // key is in the query, use the embedded discriminator schema
@@ -90,7 +91,7 @@ module.exports = function cast(schema, obj, options, context) {
               discriminatorKey != null &&
               pathLastHalf !== discriminatorKey) {
             const discriminatorVal = get(obj, pathFirstHalf + '.' + discriminatorKey);
-            if (discriminatorVal) {
+            if (discriminatorVal != null) {
               schematype = _schematype.schema.discriminators[discriminatorVal].
                 path(pathLastHalf);
             }
@@ -336,4 +337,4 @@ function _cast(val, numbertype, context) {
       }
     }
   }
-}
+}

package/lib/connection.js

@@ -549,6 +549,12 @@ Connection.prototype.openUri = function(uri, options, callback) {
         // Implicitly emits 'disconnected'
         _this.readyState = STATES.disconnected;
       });
+      client.on('left', function() {
+        if (_this.readyState === STATES.connected &&
+            get(db, 's.topology.s.coreTopology.s.replicaSetState.topologyType') === 'ReplicaSetNoPrimary') {
+          _this.readyState = STATES.disconnected;
+        }
+      });
       db.on('timeout', function() {
         _this.emit('timeout');
       });

package/lib/document.js

@@ -33,6 +33,7 @@ const deepEqual = utils.deepEqual;
 const isMongooseObject = utils.isMongooseObject;
 
 const documentArrayParent = require('./helpers/symbols').documentArrayParent;
+const getSymbol = require('./helpers/symbols').getSymbol;
 
 let DocumentArray;
 let MongooseArray;
@@ -239,10 +240,9 @@ function $__hasIncludedChildren(fields) {
  * ignore
  */
 
-function $__applyDefaults(doc, fields, skipId, exclude, hasIncludedChildren, isBeforeSetters, pathsToSkip, options) {
+function $__applyDefaults(doc, fields, skipId, exclude, hasIncludedChildren, isBeforeSetters, pathsToSkip) {
   const paths = Object.keys(doc.schema.paths);
   const plen = paths.length;
-  const init = options && 'isNew' in options ? options.isNew : false;
 
   for (let i = 0; i < plen; ++i) {
     let def;
@@ -307,21 +307,21 @@ function $__applyDefaults(doc, fields, skipId, exclude, hasIncludedChildren, isB
               continue;
             }
 
-            def = type.getDefault(doc, init);
+            def = type.getDefault(doc, false);
             if (typeof def !== 'undefined') {
               doc_[piece] = def;
               doc.$__.activePaths.default(p);
             }
           } else if (included) {
             // selected field
-            def = type.getDefault(doc, init);
+            def = type.getDefault(doc, false);
             if (typeof def !== 'undefined') {
               doc_[piece] = def;
               doc.$__.activePaths.default(p);
             }
           }
         } else {
-          def = type.getDefault(doc, init);
+          def = type.getDefault(doc, false);
           if (typeof def !== 'undefined') {
             doc_[piece] = def;
             doc.$__.activePaths.default(p);
@@ -595,16 +595,19 @@ Document.prototype.update = function update() {
  */
 
 Document.prototype.updateOne = function updateOne(doc, options, callback) {
-  return utils.promiseOrCallback(callback,
-    cb => this.$__updateOne(doc, options, cb), this.constructor.events);
-};
+  const query = this.constructor.updateOne({_id: this._id}, doc, options);
+  query._pre(cb => {
+    this.constructor._middleware.execPre('updateOne', this, [], cb);
+  });
+  query._post(cb => {
+    this.constructor._middleware.execPost('updateOne', this, [], {}, cb);
+  });
 
-/*!
- * ignore
- */
+  if (callback != null) {
+    return query.exec(callback);
+  }
 
-Document.prototype.$__updateOne = function $__updateOne(doc, options, callback) {
-  return this.constructor.updateOne({ _id: this._id }, doc, options, callback);
+  return query;
 };
 
 /**
@@ -908,9 +911,7 @@ Document.prototype.$set = function $set(path, val, type, options) {
   } else {
     for (i = 0; i < parts.length; ++i) {
       const subpath = parts.slice(0, i + 1).join('.');
-      if (this.isDirectModified(subpath) // earlier prefixes that are already
-      // marked as dirty have precedence
-          || this.get(subpath) === null) {
+      if (this.get(subpath) === null) {
         pathToMark = subpath;
         break;
       }
@@ -1282,7 +1283,7 @@ Document.prototype.get = function(path, type, options) {
     obj = adhoc.cast(obj);
   }
 
-  if (schema) {
+  if (schema != null) {
     obj = schema.applyGetters(obj, this);
   } else if (this.schema.nested[path] && options.virtuals) {
     // Might need to apply virtuals if this is a nested path
@@ -1292,6 +1293,12 @@ Document.prototype.get = function(path, type, options) {
   return obj;
 };
 
+/*!
+ * ignore
+ */
+
+Document.prototype[getSymbol] = Document.prototype.get;
+
 /**
  * Returns the schematype for the given `path`.
  *
@@ -1304,7 +1311,7 @@ Document.prototype.get = function(path, type, options) {
 
 Document.prototype.$__path = function(path) {
   const adhocs = this.$__.adhocPaths;
-  const adhocType = adhocs && adhocs[path];
+  const adhocType = adhocs && adhocs.hasOwnProperty(path) ? adhocs[path] : null;
 
   if (adhocType) {
     return adhocType;
@@ -2462,6 +2469,10 @@ Document.prototype.$toObject = function(options, json) {
     clone(options) :
     {};
 
+  if (!('flattenMaps' in options)) {
+    options.flattenMaps = defaultOptions.flattenMaps;
+  }
+
   let _minimize;
   if (options.minimize != null) {
     _minimize = options.minimize;

package/lib/helpers/document/compile.js

@@ -1,9 +1,11 @@
 'use strict';
 
-let Document;
-const get = require('lodash.get');
+const get = require('../../helpers/get');
+const getSymbol = require('../../helpers/symbols').getSymbol;
 const utils = require('../../utils');
 
+let Document;
+
 /*!
  * exports
  */
@@ -118,7 +120,7 @@ function defineKey(prop, subprops, prototype, prefix, keys, options) {
       enumerable: true,
       configurable: true,
       get: function() {
-        return this.get.call(this.$__.scope || this, path);
+        return this[getSymbol].call(this.$__.scope || this, path);
       },
       set: function(v) {
         return this.$set.call(this.$__.scope || this, path, v);

package/lib/helpers/get.js

@@ -7,13 +7,22 @@
 
 module.exports = function get(obj, path, def) {
   const parts = path.split('.');
+  let rest = path;
   let cur = obj;
   for (const part of parts) {
     if (cur == null) {
       return def;
     }
 
+    // `lib/cast.js` depends on being able to get dotted paths in updates,
+    // like `{ $set: { 'a.b': 42 } }`
+    if (cur[rest] != null) {
+      return cur[rest];
+    }
+
     cur = getProperty(cur, part);
+
+    rest = rest.substr(part.length + 1);
   }
 
   return cur == null ? def : cur;

package/lib/helpers/model/applyHooks.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const symbols = require('../../schema/symbols');
 const utils = require('../../utils');
 
 /*!
@@ -58,15 +59,26 @@ function applyHooks(model, schema, options) {
   // promises and make it so that `doc.save.toString()` provides meaningful
   // information.
 
-  const middleware = schema.s.hooks.filter(hook => {
-    if (hook.name === 'updateOne') {
-      return !!hook['document'];
-    }
-    if (hook.name === 'remove') {
-      return hook['document'] == null || !!hook['document'];
-    }
-    return true;
-  });
+  const middleware = schema.s.hooks.
+    filter(hook => {
+      if (hook.name === 'updateOne') {
+        return !!hook['document'];
+      }
+      if (hook.name === 'remove') {
+        return hook['document'] == null || !!hook['document'];
+      }
+      return true;
+    }).
+    filter(hook => {
+      // If user has overwritten the method, don't apply built-in middleware
+      if (schema.methods[hook.name]) {
+        return !hook.fn[symbols.builtInMiddleware];
+      }
+
+      return true;
+    });
+
+  model._middleware = middleware;
 
   objToDecorate.$__save = middleware.
     createWrapper('save', objToDecorate.$__save, null, kareemOptions);
@@ -74,8 +86,6 @@ function applyHooks(model, schema, options) {
     createWrapper('validate', objToDecorate.$__validate, null, kareemOptions);
   objToDecorate.$__remove = middleware.
     createWrapper('remove', objToDecorate.$__remove, null, kareemOptions);
-  objToDecorate.$__updateOne = middleware.
-    createWrapper('updateOne', objToDecorate.$__updateOne, null, kareemOptions);
   objToDecorate.$__init = middleware.
     createWrapperSync('init', objToDecorate.$__init, null, kareemOptions);
 
@@ -104,7 +114,7 @@ function applyHooks(model, schema, options) {
       return utils.promiseOrCallback(cb, callback => {
         this[`$__${method}`].apply(this,
           argsWithoutCallback.concat([callback]));
-      });
+      }, model.events);
     };
     objToDecorate[`$__${method}`] = middleware.
       createWrapper(method, originalMethod, null, customMethodOptions);

package/lib/helpers/model/discriminator.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const defineKey = require('../document/compile').defineKey;
+const get = require('../../helpers/get');
 const utils = require('../../utils');
 
 const CUSTOMIZABLE_DISCRIMINATOR_OPTIONS = {
@@ -19,9 +20,11 @@ module.exports = function discriminator(model, name, schema, tiedValue) {
     throw new Error('You must pass a valid discriminator Schema');
   }
 
-  if (model.base && model.base.options.applyPluginsToDiscriminators) {
-    model.base._applyPlugins(schema);
-  }
+  const applyPluginsToDiscriminators = get(model.base,
+    'options.applyPluginsToDiscriminators', false);
+  // Even if `applyPluginsToDiscriminators` isn't set, we should still apply
+  // global plugins to schemas embedded in the discriminator schema (gh-7370)
+  model.base._applyPlugins(schema, { skipTopLevel: !applyPluginsToDiscriminators });
 
   if (model.schema.discriminatorMapping &&
       !model.schema.discriminatorMapping.isRoot) {

package/lib/helpers/once.js

@@ -0,0 +1,12 @@
+'use strict';
+
+module.exports = function once(fn) {
+  let called = false;
+  return function() {
+    if (called) {
+      return;
+    }
+    called = true;
+    return fn.apply(null, arguments);
+  };
+};

package/lib/helpers/query/castFilterPath.js

@@ -0,0 +1,54 @@
+'use strict';
+
+module.exports = function castFilterPath(query, schematype, val) {
+  const any$conditionals = Object.keys(val).some(function(k) {
+    return k.charAt(0) === '$' && k !== '$id' && k !== '$ref';
+  });
+
+  if (!any$conditionals) {
+    return schematype.castForQueryWrapper({
+      val: val,
+      context: query
+    });
+  }
+
+  const ks = Object.keys(val);
+
+  let k = ks.length;
+
+  while (k--) {
+    const $cond = ks[k];
+    const nested = val[$cond];
+
+    if ($cond === '$not') {
+      if (nested && schematype && !schematype.caster) {
+        const _keys = Object.keys(nested);
+        if (_keys.length && _keys[0].charAt(0) === '$') {
+          for (const key in nested) {
+            nested[key] = schematype.castForQueryWrapper({
+              $conditional: key,
+              val: nested[key],
+              context: context
+            });
+          }
+        } else {
+          val[$cond] = schematype.castForQueryWrapper({
+            $conditional: $cond,
+            val: nested,
+            context: context
+          });
+        }
+        continue;
+      }
+      // cast(schematype.caster ? schematype.caster.schema : schema, nested, options, context);
+    } else {
+      val[$cond] = schematype.castForQueryWrapper({
+        $conditional: $cond,
+        val: nested,
+        context: context
+      });
+    }
+  }
+
+  return val;
+};

package/lib/helpers/query/selectPopulatedFields.js

@@ -9,16 +9,17 @@ module.exports = function selectPopulatedFields(query) {
 
   if (opts.populate != null) {
     const paths = Object.keys(opts.populate);
-    let i;
     const userProvidedFields = query._userProvidedFields || {};
     if (query.selectedInclusively()) {
-      for (i = 0; i < paths.length; ++i) {
+      for (let i = 0; i < paths.length; ++i) {
         if (!isPathInFields(userProvidedFields, paths[i])) {
           query.select(paths[i]);
+        } else if (userProvidedFields[paths[i]] === 0) {
+          delete query._fields[paths[i]];
         }
       }
     } else if (query.selectedExclusively()) {
-      for (i = 0; i < paths.length; ++i) {
+      for (let i = 0; i < paths.length; ++i) {
         if (userProvidedFields[paths[i]] == null) {
           delete query._fields[paths[i]];
         }

package/lib/helpers/query/wrapThunk.js

@@ -0,0 +1,18 @@
+'use strict';
+
+/*!
+ * A query thunk is the function responsible for sending the query to MongoDB,
+ * like `Query#_findOne()` or `Query#_execUpdate()`. The `Query#exec()` function
+ * calls a thunk. The term "thunk" here is the traditional Node.js definition:
+ * a function that takes exactly 1 parameter, a callback.
+ *
+ * This function defines common behavior for all query thunks.
+ */
+
+module.exports = function wrapThunk(fn) {
+  return function _wrappedThunk(cb) {
+    ++this._executionCount;
+
+    fn.call(this, cb);
+  };
+};

package/lib/helpers/symbols.js

@@ -4,4 +4,8 @@ exports.validatorErrorSymbol = Symbol.for('mongoose:validatorError');
 
 exports.documentArrayParent = Symbol.for('mongoose:documentArrayParent');
 
-exports.modelSymbol = Symbol.for('mongoose#Model');
+exports.modelSymbol = Symbol.for('mongoose#Model');
+
+exports.getSymbol = Symbol.for('mongoose#Document#get');
+
+exports.objectIdSymbol = Symbol.for('mongoose#ObjectId');

package/lib/helpers/update/castArrayFilters.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const castFilterPath = require('../query/castFilterPath');
+const modifiedPaths = require('./modifiedPaths');
+
+module.exports = function castArrayFilters(query) {
+  const arrayFilters = query.options.arrayFilters;
+  if (!Array.isArray(arrayFilters)) {
+    return;
+  }
+
+  const update = query.getUpdate();
+  const schema = query.schema;
+
+  const updatedPaths = modifiedPaths(update);
+
+  const updatedPathsByFilter = Object.keys(updatedPaths).reduce((cur, path) => {
+    const matches = path.match(/\$\[[^\]]+\]/g);
+    if (matches == null) {
+      return cur;
+    }
+    for (const match of matches) {
+      const firstMatch = path.indexOf(match);
+      if (firstMatch !== path.lastIndexOf(match)) {
+        throw new Error(`Path '${path}' contains the same array filter multiple times`);
+      }
+      cur[match.substring(2, match.length - 1)] = path.substr(0, firstMatch - 1);
+    }
+    return cur;
+  }, {});
+
+  for (const filter of arrayFilters) {
+    if (filter == null) {
+      throw new Error(`Got null array filter in ${arrayFilters}`);
+    }
+    const firstKey = Object.keys(filter)[0];
+
+    if (filter[firstKey] == null) {
+      continue;
+    }
+
+    const dot = firstKey.indexOf('.');
+    let filterPath = dot === -1 ?
+      updatedPathsByFilter[firstKey] + '.0' :
+      updatedPathsByFilter[firstKey.substr(0, dot)] + '.0' + firstKey.substr(dot);
+
+    if (filterPath == null) {
+      throw new Error(`Filter path not found for ${firstKey}`);
+    }
+
+    // If there are multiple array filters in the path being updated, make sure
+    // to replace them so we can get the schema path.
+    filterPath = filterPath.replace(/\$\[[^\]]+\]/g, '0');
+
+    const schematype = schema.path(filterPath);
+    if (typeof filter[firstKey] === 'object') {
+      filter[firstKey] = castFilterPath(query, schematype, filter[firstKey]);
+    } else {
+      filter[firstKey] = schematype.castForQuery(filter[firstKey]);
+    }
+  }
+};

package/lib/index.js

@@ -335,20 +335,32 @@ Mongoose.prototype.pluralize = function(fn) {
 /**
  * Defines a model or retrieves it.
  *
- * Models defined on the `mongoose` instance are available to all connection created by the same `mongoose` instance.
+ * Models defined on the `mongoose` instance are available to all connection
+ * created by the same `mongoose` instance.
+ *
+ * If you call `mongoose.model()` with twice the same name but a different schema,
+ * you will get an `OverwriteModelError`. If you call `mongoose.model()` with
+ * the same name and same schema, you'll get the same schema back.
  *
  * ####Example:
  *
  *     var mongoose = require('mongoose');
  *
  *     // define an Actor model with this mongoose instance
- *     mongoose.model('Actor', new Schema({ name: String }));
+ *     const Schema = new Schema({ name: String });
+ *     mongoose.model('Actor', schema);
  *
  *     // create a new connection
  *     var conn = mongoose.createConnection(..);
  *
- *     // retrieve the Actor model
- *     var Actor = conn.model('Actor');
+ *     // create Actor model
+ *     var Actor = conn.model('Actor', schema);
+ *     conn.model('Actor') === Actor; // true
+ *     conn.model('Actor', schema) === Actor; // true, same schema
+ *     conn.model('Actor', schema, 'actors') === Actor; // true, same schema and collection name
+ *
+ *     // This throws an `OverwriteModelError` because the schema is different.
+ *     conn.model('Actor', new Schema({ name: String }));
  *
  * _When no `collection` argument is passed, Mongoose uses the model name. If you don't like this behavior, either pass a collection name, use `mongoose.pluralize()`, or set your schemas collection name option._
  *
@@ -366,10 +378,10 @@ Mongoose.prototype.pluralize = function(fn) {
  *     var M = mongoose.model('Actor', schema, collectionName)
  *
  * @param {String|Function} name model name or class extending Model
- * @param {Schema} [schema]
+ * @param {Schema} [schema] the schema to use.
  * @param {String} [collection] name (optional, inferred from model name)
  * @param {Boolean} [skipInit] whether to skip initialization (defaults to false)
- * @return {Model}
+ * @return {Model} The model associated with `name`. Mongoose will create the model if it doesn't already exist.
  * @api public
  */
 
@@ -441,7 +453,7 @@ Mongoose.prototype.model = function(name, schema, collection, skipInit) {
       throw new _mongoose.Error.OverwriteModelError(name);
     }
 
-    if (collection) {
+    if (collection && collection !== _mongoose.models[name].collection.name) {
       // subclass current model with alternate collection
       model = _mongoose.models[name];
       schema = model.prototype.schema;
@@ -539,16 +551,18 @@ Mongoose.prototype.modelNames = function() {
  * @api private
  */
 
-Mongoose.prototype._applyPlugins = function(schema) {
+Mongoose.prototype._applyPlugins = function(schema, options) {
   if (schema.$globalPluginsApplied) {
     return;
   }
   let i;
   let len;
-  for (i = 0, len = this.plugins.length; i < len; ++i) {
-    schema.plugin(this.plugins[i][0], this.plugins[i][1]);
+  if (!options || !options.skipTopLevel) {
+    for (i = 0, len = this.plugins.length; i < len; ++i) {
+      schema.plugin(this.plugins[i][0], this.plugins[i][1]);
+    }
+    schema.$globalPluginsApplied = true;
   }
-  schema.$globalPluginsApplied = true;
   for (i = 0, len = schema.childSchemas.length; i < len; ++i) {
     this._applyPlugins(schema.childSchemas[i].schema);
   }
@@ -572,7 +586,7 @@ Mongoose.prototype.plugin = function(fn, opts) {
 };
 
 /**
- * The default connection of the mongoose module.
+ * The Mongoose module's default connection. Equivalent to `mongoose.connections][0]`, see [`connections`](#mongoose_Mongoose-connections).
  *
  * ####Example:
  *
@@ -582,10 +596,11 @@ Mongoose.prototype.plugin = function(fn, opts) {
  *
  * This is the connection used by default for every model created using [mongoose.model](#index_Mongoose-model).
  *
+ * To create a new connection, use [`createConnection()`](#mongoose_Mongoose-createConnection).
+ *
  * @memberOf Mongoose
  * @instance
- * @property connection
- * @return {Connection}
+ * @property {Connection} connection
  * @api public
  */
 
@@ -600,6 +615,29 @@ Mongoose.prototype.__defineSetter__('connection', function(v) {
   }
 });
 
+/**
+ * An array containing all [connections](connections.html) associated with this
+ * Mongoose instance. By default, there is 1 connection. Calling
+ * [`createConnection()`](#mongoose_Mongoose-createConnection) adds a connection
+ * to this array.
+ *
+ * ####Example:
+ *
+ *     const mongoose = require('mongoose');
+ *     mongoose.connections.length; // 1, just the default connection
+ *     mongoose.connections[0] === mongoose.connection; // true
+ *
+ *     mongoose.createConnection('mongodb://localhost:27017/test');
+ *     mongoose.connections.length; // 2
+ *
+ * @memberOf Mongoose
+ * @instance
+ * @property {Array} connections
+ * @api public
+ */
+
+Mongoose.prototype.connections;
+
 /*!
  * Driver dependent APIs
  */