| Platform SDK: Active Directory, ADSI, and Directory Services |
The IADs::Get method retrieves a property of a given name from the property cache. The property can be single-valued, or multi-valued. The property value is represented as either a variant for a single-valued property or a variant array (of VARIANT or bytes) for a property that allows multiple values.
HRESULT IADs::Get( BSTR bstrName, VARIANT * pvProp );
This method supports the standard return values, as well as the following:
For other return values, see ADSI Error Codes.
The IADs::Get method requires the caller to handle the single- and multi-valued property values differently. Thus, if you know that the property of interest is either single- or multi-valued, you should use the IADs::Get method to obtain the property value. This makes less a demand on ADSI to deal with different property formats and, thus, enhances performance. The following code snippet shows how you, as a caller, can handle single- and multi-valued properties when calling this method.
When a property is uninitialized, calling this method invokes an implicit call to the IADs::GetInfo method. This loads from the underlying directory store the values of the supported properties that have not been set in the cache. Any subsequent calls to IADs::Get deals with property values in the cache only. For more information about the behavior of implicit and explicit calls to IADs::GetInfo, see the discussion of IADs::GetInfo.
You can also use IADs::GetEx to retrieve property values from the property cache. However, the values are returned as a variant array of VARIANTs, regardless of whether they are single-valued or multi-valued. This means that ADSI makes an extra effort to package the returned property values in consistent data formats. This saves you, as a caller, the effort of validating the data types when you are not sure whether the returned data has single or multiple values.
The following Visual Basic code snippet retrieves the security descriptor on an object using IADs::Get.
Dim x As IADs
Dim Desc As IADsSecurityDescriptor
On Error GoTo ErrTest:
Set x = GetObject("LDAP://CN=Administrator,CN=Users,DC=Fabrikam,DC=com")
' Single-valued properties:
Debug.Print "Home Phone Number is: " & x.Get("homePhone")
' Some property values represents other ADSI objects.
' Consult your provider documentation
Set Desc = x.Get("ntSecurityDescriptor")
' Multi-valued property, assuming that multiple values have
' been assigned to the "otherHomePhone" properties. Caller must
' enumerate all the available values.
Debug.Print "Other Phone Numbers are: "
otherNumbers = x.Get("otherHomePhone")
For Each homeNum In otherNumbers
Debug.Print homeNum
Next
Exit Sub
ErrTest:
Debug.Print Hex(Err.Number)
The following is another Visual Basic code snippet that shows how to work with property values of binary data using IADs::Get and IADs::Put:
Dim oTarget As IADs
Dim Octet(5) As Byte
Dim MultiOctet(2) As Variant
Dim i As Integer, j As Integer
'Set up MultiOctetString
For i = 0 To 2
For j = 0 To 5
Octet(j) = CByte(i * j)
Next j
MultiOctet(i) = Octet
Next i
'Bind to the object and set MultiOctetString
Set oTarget=GetObject("LDAP://CN=SomeUser,CN=Users,DC=Fabrikam, DC=COM")
oTarget.Put "multiOctetString", MultiOctet
oTarget.SetInfo
Dim GetOctet As Variant
Dim Temp As Variant
'Read back and printout MultiOctetString
GetOctet = oTarget.Get("multiOctetString")
For i = LBound(GetOctet) To UBound(GetOctet)
Temp = GetOctet(i)
For j = LBound(Temp) To UBound(Temp)
Debug.Print Temp(j)
Next j
Debug.Print "----"
Next i
The following VBScript/Active Server Pages code snippet illustrates how to retrieve values of the optional properties of an object using the IADs::Get method.
<HTML>
<head><title></title></head>
<body>
<%
Dim x
On error resume next
Set x = GetObject("WinNT://Fabrikam/Administrator")
Response.Write "Object Name: " & x.Name & "<br>"
Response.Write "Object Class: " & x.Class & "<br>"
'Get optional property values of this object
Set cls = GetObject(x.Schema)
For Each op In cls.OptionalProperties
v = obj.Get(op)
if err.Number = 0 then
Response.Write "Optional Property: & op & "=" v & "<br>"
end if
Next
%>
</body>
</html>
The following C++ code snippet reads attributes with single and multiple values using IADs::Get.
HRESULT hr;
IADs *pUsr=NULL;
CoInitialize(NULL);
/////////////////////////////
// Bind to a directory object
/////////////////////////////
hr = ADsGetObject(L"WinNT://Fabrikam/Administrator,user", IID_IADs, (void**) &pUsr );
if ( !SUCCEEDED(hr) ) { return hr; }
///////////////////////////////////////
// Get a single-valued attribute
VARIANT var;
VariantInit(&var);
hr = pUsr->Get(L"FullName", &var );
if ( SUCCEEDED(hr) )
{
printf("FullName: %S\n", V_BSTR(&var) );
VariantClear(&var);
}
if ( pUsr )
{
pUsr->Release();
}
//////////////////////////////////////////////////////////////
// Get an multi-valued attribute from a service object
//////////////////////////////////////////////////////////////
IADs *pSvc = NULL;
hr = ADsGetObject(L"WinNT://Fabrikam/Account/Browser,service", IID_IADs, (void**) &pSvc );
if ( !SUCCEEDED(hr) )
{
return hr;
}
hr = pSvc->Get(L"Dependencies", &var );
if ( SUCCEEDED(hr) )
{
LONG lstart, lend;
SAFEARRAY *sa = V_ARRAY( &var );
VARIANT varItem;
// Get the lower and upper bound
hr = SafeArrayGetLBound( sa, 1, &lstart );
hr = SafeArrayGetUBound( sa, 1, &lend );
// Now iterate and print the content
VariantInit(&varItem);
printf("Getting service dependencies using IADs :\n");
for ( long idx=lstart; idx <= lend; idx++ )
{
hr = SafeArrayGetElement( sa, &idx, &varItem );
printf("%S ", V_BSTR(&varItem));
VariantClear(&varItem);
}
printf("\n");
VariantClear(&var);
}
// Clean-up
if ( pSvc )
{
pSvc->Release();
}
Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with DSClient).
Windows 95/98: Requires Windows 95 or later (with DSClient).
Header: Declared in Iads.h.
IADs, IADs::GetEx, IADs::GetInfo, Property Cache, IADs::Put, IADs::PutEx