io

Note: This is a WIP. Please help us refine this specification in Issue 190.

IO.js Public API

####io Public namespace.

---

####io.initialized Event that is called when the IO script has been completely loaded. It is recommended for storage systems to wait for this before trying to add themselves.

---

####io.isInitialized Boolean property that returns true if the io.initialized event has been fired, and false otherwise.

---

####io.systems Container for system methods.

---

####io.systems.add() Adds a storage system. Syntax: io.systems.add(system,callback,systemid) where system is an object containing a storage system's public API (see requirements), callback is a required function, called on completion, and systemid is an optional string containing the desired id for the system.

systemid is important because it enables systems to be "remembered" over multiple sessions.

Callback syntax: function(error,systemid){}. error is null in the case of success, or the error code in case of a failure. systemid is the storage system's unique id.

---

####io.systems.remove() Removes a storage system. Syntax: io.systems.remove(systemid,callback), where systemid is the unique identifier of the storage system (assigned when the system was added), and callback is an optional function that will be called upon completion.

---

####io.storages Container for storage methods.

---

####io.storages.add() Adds a storage. Syntax: io.storages.add(systemid,name,callback,storageid), where systemid is the unique identifier of the system that is responsible for the storage, name is the display name of the storage, callback is a required function, called on completion, and storageid is an optional string containing the desired id for the storage.

storageid is important because it enables storages to be "remembered" over multiple sessions.

Callback syntax: function(error,storageid){}. error is null in the case of success, or the error code in case of a failure. storageid is the storage's unique id.

---

####io.storages.get() Returns an array of unique identifiers for all registered storages.

---

####io.storages.remove() Removes a storage. Syntax: io.storages.remove(storageid,callback), where storageid is the unique identifier of the storage (assigned when the storage was added), and callback is an optional function that is called upon completion.

---

####io.files Container for file methods.

---

####io.files.add() Adds a file to a storage. Syntax: io.files.add(storageid,name,blob,callback), where storageid is the unique identifier of the storage that the file will be added to, name is the name of the file, blob is a blob object, and callback is an optional function that is called on completion.

Callback syntax: function(error){}. error is null in the case of success, or the error code in case of a failure.

---

####io.files.enumerate() Enumerates files from a storage. Syntax: io.files.enumerate(storageid,directory,callback,deep), where storageid is the unique identifier of the storage that will be enumerated, directory is the starting point of the enumeration, callback is a required function that is called on completion, and deep is an optional Boolean parameter that can be set to true to include the contents of child directories in the enumeration (false by default).

Callback syntax: function(error,files){}. error is null in the case of success, or the error code in case of a failure. files is an array of file objects, representing the result of the operation.

---

####io.files.read() Gets a file object. Syntax: io.files.read(storageid,filepath,callback), where storageid is the unique identifier of the storage that contains the files, filepath is the location of the file in that storage, and callback is a required function that is called on completion.

Callback syntax: function(error,file){}. error is null in the case of success, or the error code in case of a failure. file is a file object, representing the result of the operation.

---

####io.files.remove() Removes a file. Syntax: io.files.remove(storageid,filepath,callback), where storageid is the unique identifier of the storage that contains the files, filepath is the location of the file in that storage, and callback is an optional function that is called on completion.

Callback syntax: function(error){}. error is null in the case of success, or the error code in case of a failure.

---

####io.files.write() Writes to a file. Syntax: io.files.write(storageid,filepath,blob,callback), where storageid is the unique identifier of the storage that contains the files, filepath is the location of the file in that storage, blob is a blob object containing the new contents of the file, and callback is an optional function that is called on completion.

Callback syntax: function(error){}. error is null in the case of success, or the error code in case of a failure.