|
The WebStorage
control provides private cloud storage for uploading and
downloading shared data files which are available to your application.
This is primarily intended for use by developers to store
configuration information and other data generated by the application.
For example, you may want to store certain application settings,
and the next time a user or organization installs your software,
those settings can be downloaded and restored.
The connection to the storage service is always secure, using TLS 1.2
and AES-256 bit encryption. There are no third-party services you need
to subscribe to, and there are no additional usernames or passwords for you to manage.
Access to the service is associated with an account which is created when
you purchase a development license, and the security tokens are bound to
the runtime license key used when initializing the API. You also have
the option to compress and encrypt your data you store using the
FileEncoder control.
Terminology
When you get started with the WebStorage control, you'll notice
there is some different terminology which is used. This will
provide an overview of that terminology, and compare it to
common terms used with traditional protocols like FTP. When
accessing an FTP server, you generally deal with directories,
files, names and types (generally
whether the file is binary or text). The storage control has similar
concepts, but uses somewhat different terminology.
Application Identifiers
An application identifier (AppId) is a null-terminated string which
uniquely identifies your application. This string, used in conjunction
with your runtime license key, is used to generate an access token.
This token is used to access the storage container which contains the
data which you've stored.
It is recommended you use a standard format for the AppId
which consists of your company name, application name and optionally
a version number. Some examples of an AppId string would be:
- MyCompany.MyApplication
- MyCompany.MyApplication.1
It is important to note with these two example IDs, although
they are similar, they reference two different applications. Objects
stored using the first ID will not be accessible using the second ID.
If you want to store objects which should be shared between all
versions of the application, it is recommended you use the first
form, without the version number. If you want to store objects which
should only be accessible to a specific version of your application,
then it is recommended you use the second form which includes the
version number.
The AppId must only consist of ASCII letters, numbers, the period
and underscore character. Whitespace characters and non-ASCII Unicode
characters are not permitted. The maximum length of the string is 63
characters. It is not
required for your application to create a unique AppId. Each storage
account has a default internal AppId named SocketTools.Storage.Default.
This AppId is used if a NULL pointer or an empty string is specified.
Containers
Storage containers are somewhat analogous to directories or folders in a file
system, however they are general purpose and designed to allow you to
control how your application accesses the data that's been stored.
There are four container types which are defined by the control, and you
can think of them as types of boxes or file cabinets which you store
your data in.
It is important to keep in mind these containers are available to
all users of your application, your program controls who has access to
any particular data file. Your users will not be able to "browse" any
of the containers unless you specifically provide that capability by
implementing it in your own code. There is no public access to any of
the data which you upload, and our service does not use an open API
accessible by third parties.
webStorageGlobal
The global storage container which is available to all users of your
application. Any data stored in this container is available
to everyone who uses your software. Unless you have a specific need
to limit access to the data to a specific user or group of users,
this is the recommended container you use to store data.
webStorageDomain
The domain storage container is limited to users in the same local
domain, defined either by the name of the domain or workgroup
assigned to the computer system. This can provide a kind of
organization wide storage, but it does depend on the domain being
unique. For example, if you are using domain storage for your
application, and you have multiple customers who have systems part
of the default "Workgroup" domain, they would all share the same
container. If the domain or workgroup name changes, then data stored
in the container would no longer be available.
webStorageMachine
The local machine storage container is associated with the physical
computer system your application is running on. The machine is
identified by unique characteristics of the system, including the
boot volume GUID. Data stored in this container can only be
accessed from the application running on that particular system. If
the operating system is reinstalled, the machine ID will change and
data stored in this container would no longer be available.
webStorageUser
The current user storage container is associated with the current
user who is using your application. The user identifier is based on
the Windows Security Identifier (SID) assigned to the
account when it's created. If the user account is deleted, the data
stored in this container will no longer be available to the
application. Another user on the same computer system would not be
able to access the data in this container.
If you decide to use anything other than global storage, the data
your application stores can be orphaned if the system configuration or
user account changes. It's recommended you store critical application data
and general configuration information using webStorageGlobal and use
other non-global storage containers for configuration information
which is unique to that system and/or user which is not critical and can be
easily recreated. If you're concerned about protecting the data you
upload to global storage, you can encrypt it prior to storing it.
Objects
Storage objects are similar to files in a file system. They are discrete
blocks of data, associated with a label (name), have attributes and
are associated with a particular content type. However, an object does
not need to be an actual file on the local system. For example, you
could store an object which is a string, a pointer to a structure, or
any block of memory. You could also just store a complete file as an
object. Unlike files, you cannot perform partial reads of an object or
"seek" into certain parts of a stored object. Of course, you can
download an object, either in memory or to a local file, and perform
whatever operations you require on the data.
Labels
Object labels are similar to file names, and are a way to identify a stored
object instead of using its internal object ID. However, there
are some important differences. The most significant difference being labels
are case-sensitive, unlike Windows file names. An object with the
label "AppConfig" is considered to be different than one with the
label "appconfig". Labels can contain Unicode characters, but they
cannot contain control characters.
You can also use forward slashes or backslash characters in the
label, but it's important to note objects are not stored in a
hierarchical structure. Your application can store objects using a
folder-like structure, but it's not something which is enforced by the
API.
Media Type
Each object your application stores is associated with a media type
(also called a content type) which identifies the object's data. This
uses the standard MIME media type designations, such as "text/plain"
or "application/octet-stream". Your application can explicitly specify
the media type you want to associate with the object, or you can have
the API choose for you, based on the contents of the object and using
the label as a hint for what it may contain. For example, if you
create an object with the label "AppConfig.xml" and it
contains text, then the API will select "text/xml" as the default
media type.
Initialization
The first step your application must take is to initialize the
control and then open a storage container. The following methods are available for use by your
application:
Initialize
Initialize the control and validate the runtime license key for the
current process. This method is normally not used if the control is
placed on a form in languages such as Visual Basic. However, if the
control is being created dynamically using a function similar to
CreateObject, then the application must call this method to
initialize the component before setting any properties or calling any
other methods in the control.
Open
Opens a storage container for your application. Subsequent operations,
such as storing, retrieving and copying objects will be performed
within this container.
Close
Close the storage container and release the resources allocated for
the session.
Uninitialize
Release all resources which have been allocated for the current
process. This is the last method call that the application should make
prior to terminating. This is only necessary if the application has
previously called the
Initialize method.
Data Storage
The control provides methods to upload and download to the storage
container. You can store the contents of local files, or you can create objects from
memory using strings or byte arrays.
GetData
Download object data and store it in a string or byte array
provided by the caller.
GetFile
Download object data and store it in a file on the local system.
PutData
Upload object data in a string or byte array and store it as an
object in the current container. This function would typically be used
to store binary data, including compressed or encrypted text.
PutFile
Upload the the contents of a local file and store it as an object in
the current container.
Data Management
The data management methods allow you to obtain information about
stored objects and perform typical operations such as copying, renaming
and deleting objects from the container.
FindFirst
Enables your application to search for and enumerate objects in a
container based on their label and/or their media type. This method
is used in conjunction with the
FindNext
method to list all matching objects in a container.
CompareData
Compares the contents of a string or byte array with the data stored
in an object. This method can be used to determine if the contents of the
buffer have changed since the data was previously stored using the
PutData method.
CompareFile
Compares the contents of a local file with the data in a stored object.
This method can be used to determine if the contents of a file have
changed since it was previously stored using the
PutFile method.
Copy
Copies the contents of a stored object to a new container, or
duplicating the object within the same container using a different
label.
Move
Moves the contents of a stored object to a new container.
Rename
Changes the label associated with a stored object. The new label for
the object cannot already exist in the same container. If you want to
change the label to one already assigned to an existing object, the
object must first be deleted.
Delete
Removes the stored object from the container. This operation is
immediate and permanent. Deleted objects cannot be recovered by the
application at a later time.
DeleteAll
Deletes all objects which are stored in the current open container.
This method resets the container back to its initial state, deleting
all object metadata from the database and removing all stored data.
This operation is immediate and the objects stored in the container
are permanently deleted. They cannot be recovered by your application.
Other Methods
Several additional methods are available, allowing your application register and de-register
custom application
identifiers and validate object labels.
RegisterId
Register a new application identifier (AppId) to be used to access a
storage container. It is not required you create a unique
application ID, but it can be helpful to distinguish stored content
between different versions of your applications.
UnregisterId
Unregister an application identifier which was previously registered
by your application. You should be extremely careful when using this
function because it permanently delete all stored objects
created using the AppId value. Internally it revokes the access token
granted to your application and causes the server to expunge all
objects in the container associated with the token.
ValidateId
A method which can be used to validate an application
identifier, ensuring it is valid and has been registered.
ValidateLabel
A method which can be used to validate an object label to
ensure it does not contain any invalid characters. This would be
primarily used by applications which allow a user to specify the label
names for the objects being stored.
|