IDirectoryObject

IDirectoryObject インターフェイスは、ディレクトリ サービス オブジェクトへの直接アクセスをクライアントに提供する非オートメーション COM インターフェイスです。

IDirectoryObject::GetObjectInformation メソッドは、ディレクトリ サービス オブジェクトの識別情報と場所に関するデータを含む ADS_OBJECT_INFO 構造体へのポインターを取得します。

このメソッドは、データが正常に取得された場合の S_OK を含む標準的な戻り値を返します。詳細およびその他の戻り値については、ADSI Error Codes を参照してください。

呼び出し元は、GetObjectInformation 関数によって作成された ADS_OBJECT_INFO 構造体を解放するために、FreeADsMem ヘルパー関数を呼び出す必要があります。

オートメーション クライアントは IADs::GetInfo を呼び出す必要があります。

例

次の C++ コード例は、IDirectoryObject インターフェイスを実装するオブジェクト (m_pDirObject) の GetObjectInformation メソッドを使用して、オブジェクト データ (ADS_OBJECT_INFO) を取得する方法を示しています。

ADS_OBJECT_INFO *pInfo;
HRESULT hr;
 
hr = m_pDirObject->GetObjectInformation(&pInfo);
if (!SUCCEEDED(hr) )
{
   return;
}
 
//////////////////////////
// Show the attributes 
/////////////////////////
 
printf("RDN: %S\n", pInfo->pszRDN);
printf("ObjectDN: %S\n", pInfo->pszObjectDN);
printf("Parent DN: %S\n", pInfo->pszParentDN);
printf("Class Name: %S\n", pInfo->pszClassName);
printf("Schema DN: %S\n", pInfo->pszSchemaDN);
 
///////////////////////////////////////////////////////////
// Remember to clean up the memory using FreeADsMem.
//////////////////////////////////////////////////////////
FreeADsMem( pInfo );

ディレクトリ サービス オブジェクトの 1 つ以上の指定された属性を取得します。

このメソッドは、標準的な値に加えて次の値を返します。

詳細およびその他の戻り値については、ADSI Error Codes を参照してください。

ADSI は、ppAttributeEntries パラメーターで返される ADS_ATTR_INFO 構造体の配列のメモリを割り当てます。呼び出し元は、配列を解放するために FreeADsMem を呼び出す必要があります。

ppAttributeEntries で返される属性の順序は、必ずしも pAttributeNames で要求した順序と同じとは限りません。

IDirectoryObject::GetObjectAttributes メソッドは、要求された属性のスキーマ定義を読み取ろうとします。これにより、ADS_ATTR_INFO 構造体に含まれる ADSVALUE 構造体で属性値を適切な形式で返すことができます。ただし、GetObjectAttributes はスキーマ定義が利用できない場合でも成功することがあります。その場合、ADS_ATTR_INFO 構造体の dwADsType メンバーは ADSTYPE_PROV_SPECIFIC を返し、値は ADS_PROV_SPECIFIC 構造体で返されます。GetObjectAttributes 呼び出しの結果を処理する際は、データが期待した形式で返されたことを確認するために dwADsType を検証してください。

例

次のコード例は、IDirectoryObject::GetObjectAttributes メソッドの使用方法を示しています。

HRESULT hr;
IDirectoryObject *pDirObject = NULL;
 
hr = ADsGetObject(L"LDAP://CN=Jeff Smith,OU=Sales,DC=Fabrikam,DC=com",
                     IID_IDirectoryObject, 
                     (void**) &pDirObject );
 
if ( SUCCEEDED(hr) )
{
    ADS_ATTR_INFO *pAttrInfo=NULL;
    DWORD dwReturn;
    LPWSTR pAttrNames[]={L"givenName",L"sn", L"otherTelephone" };
    DWORD dwNumAttr=sizeof(pAttrNames)/sizeof(LPWSTR);

    //////////////////////////////////////////////////////
    // Get attribute values requested.
    // Be aware that the order is not necessarily the 
    // same as requested using pAttrNames.
    //////////////////////////////////////////////////////
    hr = pDirObject->GetObjectAttributes( pAttrNames, 
                                        dwNumAttr, 
                                        &pAttrInfo, 
                                        &dwReturn );
     
    if ( SUCCEEDED(hr) )
    {
        for(DWORD idx = 0; idx < dwReturn; idx++ )
        {
            if ( _wcsicmp(pAttrInfo[idx].pszAttrName,L"givenName") == 0 )
            {
                switch (pAttrInfo[idx].dwADsType)
                {
                    case ADSTYPE_CASE_IGNORE_STRING:
                        printf("First Name: %S\n", pAttrInfo[idx].pADsValues->CaseIgnoreString);
                        break;
         
                    case ADSTYPE_PROV_SPECIFIC:
                        printf("First Name: %S\n", pAttrInfo[idx].pADsValues->ProviderSpecific.lpValue);
                        break;
         
                    default:
                        printf("Invalid ADsType: %d\n", pAttrInfo[idx].dwADsType);
                        break;
                }
            }
            else if ( _wcsicmp(pAttrInfo[idx].pszAttrName, L"sn") == 0 )
            {
                switch (pAttrInfo[idx].dwADsType)
                {
                    case ADSTYPE_CASE_IGNORE_STRING:
                        printf("Last Name: %S\n", pAttrInfo[idx].pADsValues->CaseIgnoreString);
                        break;
         
                    case ADSTYPE_PROV_SPECIFIC:
                        printf("Last Name: %S\n", pAttrInfo[idx].pADsValues->ProviderSpecific.lpValue);
                        break;
         
                    default:
                        printf("Invalid ADsType: %d\n", pAttrInfo[idx].dwADsType);
                        break;
                }
            }
            else if ( _wcsicmp(pAttrInfo[idx].pszAttrName, L"otherTelephone") == 0  )
            {   // Print the multi-valued property, "Other Telephones".
                switch (pAttrInfo[idx].dwADsType)
                {
                    case ADSTYPE_CASE_IGNORE_STRING:
                        printf("Other Telephones:");
                        for (DWORD val=0; val < pAttrInfo[idx].dwNumValues; val++) 
                        printf("  %S\n", pAttrInfo[idx].pADsValues[val].CaseIgnoreString);
                        break;
         
                    case ADSTYPE_PROV_SPECIFIC:
                        printf("Other Telephones:");
                        for (DWORD val=0; val < pAttrInfo[idx].dwNumValues; val++) 
                        printf("  %S\n", pAttrInfo[idx].pADsValues[val].CaseIgnoreString);
                        break;
         
                    default:
                        printf("Other Telephones:");
                        for (DWORD val=0; val < pAttrInfo[idx].dwNumValues; val++) 
                        printf("  %S\n", pAttrInfo[idx].pADsValues[val].CaseIgnoreString);
                        break;
                }
            }
        }

        /////////////////////////////////////////////////////////////
        // Use FreeADsMem for all memory obtained from the ADSI call. 
        /////////////////////////////////////////////////////////////
        FreeADsMem( pAttrInfo );
    
    }
 
    pDirObject->Release();
}

IDirectoryObject::SetObjectAttributes メソッドは、ADS_ATTR_INFO 構造体で定義された 1 つ以上の指定されたオブジェクト属性のデータを変更します。

このメソッドは、属性が正常に設定された場合の S_OK を含む標準的な戻り値を返します。

詳細およびその他の戻り値については、ADSI Error Codes を参照してください。

Active Directory (LDAP プロバイダー) では、IDirectoryObject::SetObjectAttributes メソッドはトランザクション処理される呼び出しです。属性はすべてコミットされるか、すべて破棄されます。他のディレクトリ プロバイダーでは、呼び出しがトランザクション処理されない場合があります。

Active Directory では、複数値属性に重複する値を許可しません。ただし、SetObjectAttributes を呼び出して Active Directory オブジェクトの複数値属性に重複する値を追加した場合、SetObjectAttributes 呼び出しは成功しますが、重複する値は無視されます。

同様に、SetObjectAttributes を使用して Active Directory オブジェクトの複数値プロパティから 1 つ以上の値を削除する場合、指定した値の一部またはすべてがプロパティに設定されていなくても、操作は成功します。

例

次の C++ コード例は、ユーザー オブジェクトの sn 属性を、大文字と小文字を区別しない文字列として Price の値に設定します。

HRESULT hr;
IDirectoryObject *pDirObject=NULL;
DWORD  dwReturn;
ADSVALUE  snValue;
ADS_ATTR_INFO attrInfo[] = { {L"sn",ADS_ATTR_UPDATE, ADSTYPE_CASE_IGNORE_STRING, &snValue, 1} };
DWORD dwAttrs = sizeof(attrInfo)/sizeof(ADS_ATTR_INFO); 
 
snValue.dwType=ADSTYPE_CASE_IGNORE_STRING;
snValue.CaseIgnoreString = L"Price";
 
hr = ADsGetObject(L"LDAP://CN=Jeff Smith,OU=Sales,DC=Fabrikam,DC=com",
        IID_IDirectoryObject, 
        (void**) &pDirObject );
 
if ( SUCCEEDED(hr) )
{
    hr = pDirObject->SetObjectAttributes(attrInfo, dwAttrs, &dwReturn);

    pDirObject->Release();
}

現在のディレクトリ サービス オブジェクトの子を作成します。

このメソッドは、操作が成功した場合の S_OK を含む標準的な戻り値を返します。詳細およびその他の戻り値については、ADSI Error Codes を参照してください。

作成時に初期化するすべての属性を pAttributeEntries 配列で指定します。オプションの属性を指定することもできます。このメソッドでディレクトリ オブジェクトを作成する場合、いずれかの文字列データ型を持つ属性を空または長さ 0 にすることはできません。

例

次の C/C++ コード例は、IDirectoryObject::CreateDSObject メソッドを使用してユーザー オブジェクトを作成する方法を示しています。

HRESULT    hr;
IDirectoryObject *pDirObject=NULL;
ADSVALUE   sAMValue;
ADSVALUE   uPNValue;
ADSVALUE   classValue;
LPDISPATCH pDisp;
 
ADS_ATTR_INFO  attrInfo[] = 
{  
   { L"objectClass", ADS_ATTR_UPDATE, 
                       ADSTYPE_CASE_IGNORE_STRING, &classValue, 1 },
   {L"sAMAccountName", ADS_ATTR_UPDATE, 
                       ADSTYPE_CASE_IGNORE_STRING, &sAMValue, 1},
   {L"userPrincipalName", ADS_ATTR_UPDATE, 
                      ADSTYPE_CASE_IGNORE_STRING, &uPNValue, 1},
};
DWORD dwAttrs = sizeof(attrInfo)/sizeof(ADS_ATTR_INFO); 
 
classValue.dwType = ADSTYPE_CASE_IGNORE_STRING;
classValue.CaseIgnoreString = L"user";
 
sAMValue.dwType=ADSTYPE_CASE_IGNORE_STRING;
sAMValue.CaseIgnoreString = L"jeffsmith";
 
uPNValue.dwType=ADSTYPE_CASE_IGNORE_STRING;
uPNValue.CaseIgnoreString = L"jeffsmith@Fabrikam.com";
 
hr = ADsGetObject(L"LDAP://OU=Sales,DC=Fabrikam,DC=com",
          IID_IDirectoryObject, (void**) &pDirObject );
 
if ( SUCCEEDED(hr) )
{
    hr = pDirObject->CreateDSObject( L"CN=Jeff Smith",  attrInfo, 
                                    dwAttrs, &pDisp );

    if ( SUCCEEDED(hr) )
    {
         // Use the DS object.

         pDisp->Release();
    }

    pDirObject->Release();
}

ディレクトリ ツリー内のリーフ オブジェクトを削除します。

このメソッドは、操作が成功した場合の S_OK を含む標準的な戻り値を返します。詳細およびその他の戻り値については、ADSI Error Codes を参照してください。

コンテナー オブジェクトとその子を削除するには、IADsDeleteOps::DeleteObject メソッドを使用します。

例

次の C/C++ コード例は、ユーザー オブジェクトを削除する方法を示しています。

HRESULT hr;
IDirectoryObject *pDirObject=NULL;
hr = ADsGetObject(L"LDAP://OU=Sales,DC=Fabrikam,DC=com",
    IID_IDirectoryObject, (void**) &pDirObject );
 
if ( SUCCEEDED(hr) )
{
    hr = pDirObject->DeleteDSObject( L"CN=Jeff Smith" );

    pDirObject->Release();
}