| \n |
| Microsoft Invisible Computing |
The INameSpace interface provides methods for manipulating namespaces and the run-time library provides a function and flags for accessing the system namespace.
C type for interface pointer:
Extends IUnknown
Extended by INameRanges
Implemented by CNameSpace CNameRanges FatName RomName HostName NtName TmpFs
See also CurrentNameSpace BindToObject
Methods: Register Unregister Bind FindNext GetCapabilities
Adds the specified name and its associated object to the namespace.
Removes a registered {name, object} pair from the namespace.
Translates a name into an object reference. This method either creates or references the object associated with the specified name and returns a pointer to that object.
Returns the next name that appears in the namespace or subnamespace.
Reports the capabilities supported by an object registered under the specified name. These capabilities are those defined by the INameSpace.Register method and have no meaning for the namespace itself.
Bit values for Flags arguments in INameSpace methods.
Adds the specified name and its associated object to the namespace.
SCODE Register(
/*in,this*/ PINAMESPACE iThis,
/*in*/ const _TCHAR * pName,
/*in*/ PIUNKNOWN pObj,
/*in*/ NAME_SPACE_FLAGS Flags,
/*in,optional*/ PINAMESPACE pServerNameSpace)Returned if the new {name, object} pair was successfully registered in the namespace and a previously registered object under that name was deleted.
Returned if the NAME_SPACE_FAILIFEXIST flag is set and the name is already registered with an object in the namespace.
Points to a null-terminated string that contains the name to be associated with an object.
A pointer to the object associated with the pName string.
Each bit is a flag that the caller sets to one to select the processing option represented by the flag. Multiple flags may be set to select multiple options simultaneously.
This parameter is not used in the current implementation and should be NULL.
Example Register
UINT TestRefs = 0;
/* MyObject implements only IUnknown. */
struct MyObject: IUnknown {
SCODE MCT QueryInterface(REFIID riid, void **ppvObject);
UINT MCT AddRef(void);
UINT MCT Release(void);
};
SCODE MCT MyObject::QueryInterface(REFIID riid, void **ppvObject)
{
if (UuidCmp(IID_IUnknown, riid)) {
this->AddRef();
*ppvObject = this;
return S_OK;
} else {
*ppvObject = NULL;
return E_NO_INTERFACE;
}
}
UINT MCT MyObject::AddRef(void)
{
UINT Refs = AtomicInc(&TestRefs);
_tprintf(_TEXT("refs=%d (after inc in AddRef)\n"), Refs);
return Refs;
}
UINT MCT MyObject::Release(void)
{
UINT Refs = AtomicDec(&TestRefs);
_tprintf(_TEXT("refs=%d (after dec in Release)\n"), Refs);
return Refs;
}
int _tmain()
{
PIUNKNOWN pObject;
/* Pointer and reference to the current namespace */
INameSpace *pNS = CurrentNameSpace();
/* Initialize an unknown object as MyObject */
IUnknown *pUnknwn = new MyObject;
SCODE StatusCode;
_TCHAR *pName = _TEXT("MyObject");
StatusCode = pNS->Register(pName, pUnknwn, 0, NULL);
if(FAILED(StatusCode)) {
_tprintf(_TEXT("Registering %s failed with error code %08x.\n"),
pName, StatusCode);
exit(0);
}
_tprintf(_TEXT("Registering %s succeeded.\n"), pName);
/* Verify that MyObject is registered in system namespace. */
StatusCode = pNS->Bind(pName, 0, &pObject);
if (StatusCode != S_OK) {
_tprintf(_TEXT("Error in registering object name!\n"));
exit(0);
}
_tprintf(_TEXT("Succeeded in registering object name.\n"));
/* Other threads use the object. */
/* ... */
return 0;
}
See also CurrentNameSpace NAME_SPACE_FLAGS
SCODE INameSpace::Register(
/*in*/ const _TCHAR * pName,
/*in*/ PIUNKNOWN pObj,
/*in*/ NAME_SPACE_FLAGS Flags,
/*in,optional*/ PINAMESPACE pServerNameSpace)Removes a registered {name, object} pair from the namespace.
SCODE Unregister(
/*in,this*/ PINAMESPACE iThis,
/*in*/ const _TCHAR * pName)No object is registered in the namespace with the specified pName.
Contains the address of a null-terminated string specifying the name of an object previously registered in the namespace.
Example Unregister
/* Pointer and reference to the system namespace. */
INameSpace *pNS;
SCODE StatusCode;
IUnknown *pObject;
_TCHAR *pName = _TEXT("MyObject");
/* "MyObject" must already be registered in the namespace. */
_tprintf(_T("Attempting to unregister object name \"%s\".\n"),
pName);
pNS = CurrentNameSpace();
StatusCode = pNS->Unregister(pName);
if(StatusCode != S_OK) {
_tprintf(_T("Failed to unregister object name!\n"));
exit(0);
}
/* Verify that object name is no longer registered. */
StatusCode = pNS->Bind(pName, 0, &pObject);
if (StatusCode == S_OK) {
_tprintf(_T("Error in unregistering object name!\n"));
pObject->Release();
exit(0);
}
_tprintf(_T("Succeeded in unregistering object name.\n"));
See also CurrentNameSpace
SCODE INameSpace::Unregister(
/*in*/ const _TCHAR * pName)Translates a name into an object reference. This method either creates or references the object associated with the specified name and returns a pointer to that object.
SCODE Bind(
/*in,this*/ PINAMESPACE iThis,
/*in*/ const _TCHAR * pName,
/*in*/ NAME_SPACE_FLAGS Flags,
/*out*/ PIUNKNOWN* ppUnk)Returned if the name was successfully bound to the newly created object in the namespace and another entry previously registered under that name was deleted. This will occur only if the NAME_SPACE_CREATE option was specified by Flags.
Returned if the name is already registered in the namespace and the NAME_SPACE_FAILIFEXIST option was specified by Flags.
One of the parameters is an illegal value, such as an empty string.
Could not create a new entry due to insufficient memory.
No object is registered in the namespace with the specified pName.
Address of a null-terminated string that specifies the name registered in the namespace for the object.
Each bit is a flag that the caller sets to one to select the processing option represented by the flag. Multiple flags may be set to select multiple options simultaneously.
On successful return, the location pointed to by this parameter contains the address of an interface pointer to the object. Note that it is returned as a pointer to an object of class IUnknown and that one reference is taken on the returned object.
This method can create only INameSpace interface objects; use INameSpace.Register to insert any other type of object.
The method returns a pointer to the object in the namespace that is registered under the specified name. Since an IUnknown interface pointer points to the registered object, the IUnknown.QueryInterface method can be used to obtain an interface pointer to the correct type. After obtaining the pointer to the object, you can use that object and call its methods. Remember to release the IUnknown object properly.
Example Bind
/* If a namespace object named "MyNamespace/" already exists, get
* a pointer to it. Otherwise, create a new namespace object.
*/
INameSpace *pSysNS;
IUnknown *pUnknown;
SCODE StatusCode;
_TCHAR ObjName[] = _TEXT("MyNamespace/");
/* Get a pointer to the object registered as "MyNamespace/". */
pSysNS = CurrentNameSpace();
StatusCode = pSysNS->Bind(ObjName, 0, &pUnknown);
if (FAILED(StatusCode)) {
/* Need to create namespace object named "MyNamespace/" */
_tprintf(_TEXT("Namespace \"%s\" does not exist--create it.\n"),
ObjName);
StatusCode = pSysNS->Bind(ObjName, NAME_SPACE_CREATE, &pUnknown);
if (FAILED(StatusCode)) {
_tprintf(_TEXT("Failed to create namespace %s.\n"), ObjName);
exit(0);
}
}
_tprintf(_TEXT("The namespace object named \"%s\""), ObjName);
_tprintf(_TEXT(" is located at address %08x\n"), (ADDRESS) pUnknown);
pUnknown->Release();
See also ICRuntime.BindToObject CurrentNameSpace INameSpace.Register NAME_SPACE_FLAGS
SCODE INameSpace::Bind(
/*in*/ const _TCHAR * pName,
/*in*/ NAME_SPACE_FLAGS Flags,
/*out*/ PIUNKNOWN* ppUnk)Returns the next name that appears in the namespace or subnamespace.
SCODE FindNext(
/*in,this*/ PINAMESPACE iThis,
/*in,optional*/ const _TCHAR * pPrefix,
/*in,optional*/ const _TCHAR * pPrevious,
/*out*/ _TCHAR * pBuffer,
/*in*/ UINT BufSize,
/*out,optional*/ UINT * pStrLen)The search located the first (subsequent) entry in the namespace and the name was successfully copied to the buffer. More entries follow.
No additional entries exist. If the namespace contains a single (additional) name, the name was successfully copied to the buffer and a nonzero string length was written to the location pointed to by pStrLen. If the namespace is empty, a value of zero was written to the location pointed to by pStrLen.
An entry exists, but its name is too long to fit in the buffer supplied. The location pointed to by pStrLen was updated to reflect the actual length of the name.
An entry may exist, but its name is too long to fit in the buffer supplied. The needed size is unknown and was not updated. This only happens when pPrevious was a recursive string (i.e. it referred to a subdirectory). pStrLen was NOT updated.
No object is registered in the namespace with the specified pPrefix.
This parameter is used to start the search at a given subnamespace. A simple namespace implementation might not support subnamespaces. Use NULL to specify the root namespace.
Contains the address of a null-terminated string specifying a name previously returned by the INameSpace.FindNext method. This parameter typically points to the same location as the pBuffer parameter (during iterations). Note that if pPrevious is either a null pointer or points to an empty string, the method returns the first name that appears in the given namespace.
A pointer to a buffer into which the method, if successful, copies the name of the object.
Number of bytes in the buffer pointed to by the pBuffer parameter.
A pointer to an integer variable into which the method, if successful, copies the length of the string that is written to the buffer pointed to by pBuffer. The length is specified as the number of characters in the string containing the name, excluding the terminating null character. Note that in the case of a Unicode string, the number of characters does not equal the number of bytes.
An error code is never returned if an entry that matches pPrevious exists in the namespace.
The status code S_NO_MORE_ENTRIES indicates that the name pointed to by pString was successfully matched to an entry in the namespace. It also indicates that the namespace contains no more entries, but this can happen in one of two ways.
First, it may be that the namespace entry that matches the name pointed to by pString is the next-to-last entry in the namespace. In this case, the method copies the name from the last entry into the buffer pointed to by pBuffer and writes the name's string length to the location pointed to by pStrLen.
Second, it may be that the name matching the one pointed to by pString is the last entry. In this case, the method writes zero to the location pointed to by pStrLen.
Example FindNext
/* Find all entries in system namespace. */
#define BUFLEN 20
#define BUFSIZE BUFLEN*sizeof(_TCHAR)
INameSpace *pNS;
SCODE StatusCode;
_TCHAR Buf[BUFLEN];
UINT Len;
_tprintf(_T("Search for all names in system namespace.\n"));
pNS = CurrentNameSpace();
StatusCode = pNS->FindNext(NULL, NULL, Buf, BUFSIZE, &Len);
do {
switch (StatusCode) {
case S_OK:
_tprintf(_T("The next name in the namespace is \"%s\".\n"),Buf);
_tprintf(_T("The string length of \"%s\" is %d.\n"), Buf, Len);
break;
case S_NO_MORE_ENTRIES:
_tprintf(_T("The last name in the namespace is \"%s\".\n"),Buf);
_tprintf(_T("The string length of \"%s\" is %d.\n"), Buf, Len);
break;
case S_BUFFER_TOO_SMALL:
_tprintf(_T("The name is %d characters long, which is\n"), Len);
_tprintf(_T("too long to fit in the buffer supplied.\n"));
break;
default:
_tprintf(_T("An error has occurred!\n"));
break;
}
StatusCode = pNS->FindNext(_T(""), Buf, Buf, BUFSIZE, &Len);
} while (StatusCode == S_OK);
Example FindFirst
/* Find first entry in system namespace. */
#define BUFLEN 20
#define BUFSIZE BUFLEN*sizeof(_TCHAR)
INameSpace *pNS;
SCODE StatusCode;
_TCHAR Buf[BUFLEN];
UINT Len;
_tprintf(_T("Search for first name in system namespace.\n"));
pNS = CurrentNameSpace();
StatusCode = pNS->FindNext(NULL, NULL, Buf, BUFSIZE, &Len);
switch (StatusCode) {
case S_OK:
_tprintf(_T("The first name in the namespace is \"%s\".\n"), Buf);
_tprintf(_T("The string length of \"%s\" is %d.\n"), Buf, Len);
break;
case S_NO_MORE_ENTRIES:
_tprintf(_T("The only name in the namespace is \"%s\".\n"), Buf);
_tprintf(_T("The string length of \"%s\" is %d.\n"), Buf, Len);
break;
case S_BUFFER_TOO_SMALL:
_tprintf(_T("The name is %d characters long.\n"), Len);
_tprintf(_T("It's too long to fit in the buffer supplied.\n"));
break;
default:
_tprintf(_T("The namespace is empty.\n"));
break;
}
SCODE INameSpace::FindNext(
/*in,optional*/ const _TCHAR * pPrefix,
/*in,optional*/ const _TCHAR * pPrevious,
/*out*/ _TCHAR * pBuffer,
/*in*/ UINT BufSize,
/*out,optional*/ UINT * pStrLen)Reports the capabilities supported by an object registered under the specified name. These capabilities are those defined by the INameSpace.Register method and have no meaning for the namespace itself.
SCODE GetCapabilities(
/*in,this*/ PINAMESPACE iThis,
/*in*/ const _TCHAR * pName,
/*out*/ NAME_SPACE_FLAGS * pFlags)Contains the address of a null-terminated string specifying a valid name within the namespace.
On successful return, contains flag values that describe the capabilities of the named object.
SCODE INameSpace::GetCapabilities(
/*in*/ const _TCHAR * pName,
/*out*/ NAME_SPACE_FLAGS * pFlags)Bit values for Flags arguments in INameSpace methods.
Underlying C type:
Read access.
Write access.
Windows 2000 compat. Ignored.
Windows 2000 compat. Ignored.
Create a new object. Destroys existing object if any (in this case S_ALREADY_EXISTS is returned.
Together with CREATE makes the call return E_ALREADY_EXISTS if there was an existing object with the specified name with the existing object intact.
The registered object should be treated as a subnamespace.
Do not follow symbolic links.
Treat name as is without splitting at slashes.
Compatibility flag. Ignored by most file systems. On hostfs it is passed through to Windows.
Type NAME_SPACE_FLAGS is defined as unsigned integer. Each bit in a variable of this type is treated as a flag controlling a particular option. When the bit is set, the option is selected or enabled. Zero, one, or multiple flags may be set within the variable.
Individual flag bits are specified by symbolic constants, each of which is a value where the designated flag bit is set to one and all other bits are set to zero. The value of a variable of type NAME_SPACE_FLAGS is formed by a bitwise OR of one or more of these flags. A value of zero specifies that none of the flags is set.
| ©2006 Microsoft Corporation. All rights reserved. | Terms of Use | Privacy Statement | Accessibility | End User License Agreement |