The WebRegisterAppId function registers an
application ID with the server which uniquely identifies the
application that is requesting access to the storage container.
The ID 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 an application ID string is 64 characters,
including the terminating null character.
It is recommended that you use a standard format for the application
ID that consists of your company name, application name and
optionally a version number. For example:
- MyCompany.MyApplication
- MyCompany.MyApplication.1
It is important to note that 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 that should be shared between
all versions of the application, it is recommended that you use the
first form, without the version number. If you want to store objects
that should only be accessible to a specific version of your application,
then it is recommended that you use the second form that includes the
version number.
It is safe to call this function with an application ID that was
previously registered. If the provided application ID has already been
registered, this function will succeed. You can choose to call this
function every time your application starts to ensure the application
has been registered correctly.
If you no longer wish to use an application ID you have previously
registered, you can call the WebUnregisterAppId
function. Exercise caution when unregistering an application. This
will cause all objects stored using that ID to be deleted by the
storage server. Once an application ID has been unregistered, the
operation is permanent. Calling WebUnregisterAppId
and then WebRegisterAppId again using the same ID
will force the system to create new access tokens for your
application. You will not be able to regain access to the objects that
were previously stored using that ID.
The application ID is intended to be an application defined
human-readable string that uniquely identifies your application. If you want to
obtain the internal storage ID associated with your application, use
the WebGetStorageId function. The storage ID is a
fixed-length string of letters and numbers guaranteed to be unique
across all applications that you register.
It is not required for your application to create a unique
application ID. Each storage account has a default internal application
ID named SocketTools.Storage.Default. This default ID is used
if a NULL pointer or an empty string is specified to functions like
WebOpenStorage. It is intended to identify storage
available to all applications that you create.
To enumerate the application IDs that you have created, use the
WebGetFirstApplication and WebGetNextApplication
functions.
HSTORAGE hStorage = INVALID_HANDLE;
LPCTSTR lpszAppId = _T("MyCompany.WebTest.1");
LPCTSTR lpszLocalFile = _T("TestDocument.pdf");
LPCTSTR lpszObjectLabel = _T("TestDocument.pdf");
WEB_STORAGE_OBJECT webObject = { 0, };
BOOL bSuccess = FALSE;
if (!WebRegisterAppId(lpszAppId))
{
tprintf(_T("Unable to register the application ID"));
_exit(0);
}
hStorage = WebOpenStorage(lpszAppId, WEB_STORAGE_GLOBAL);
if (hStorage == INVALID_HANDLE)
{
tprintf(_T("Unable to open global storage for this application"));
_exit(0);
}
bSuccess = WebPutFileEx(hStorage,
lpszLocalFile,
lpszObjectLabel,
NULL,
WEB_OBJECT_DEFAULT,
0,
&webObject);
if (bSuccess)
{
_tprintf(_T("Object: %s\n"), webObject.szObjectId);
_tprintf(_T("Label: %s\n"), webObject.szLabel);
_tprintf(_T("Size: %I64u\n"), webObject.dwObjectSize);
_tprintf(_T("Digest: %s\n"), webObject.szDigest);
_tprintf(_T("Content: %s\n"), webObject.szContent);
}
else
{
DWORD dwError = WebGetLastError();
TCHAR szError[128];
WebGetErrorString(dwError, szError, 128);
_tprintf(_T("WebPutFileEx failed, error 0x%08lX (%s)\n"), dwError, szError);
}
WebCloseStorage(hStorage);