Função ADsOpenObject (adshlp.h)

Artigo
08/22/2023

A função ADsOpenObject se associa a um objeto ADSI usando credenciais explícitas de nome de usuário e senha. ADsOpenObject é uma função wrapper para IADsOpenDSObject e é equivalente ao método IADsOpenDSObject::OpenDsObject .

Sintaxe

HRESULT ADsOpenObject(
  [in]  LPCWSTR lpszPathName,
  [in]  LPCWSTR lpszUserName,
  [in]  LPCWSTR lpszPassword,
  [in]  DWORD   dwReserved,
  [in]  REFIID  riid,
  [out] void    **ppObject
);

Parâmetros

[in] lpszPathName

Tipo: LPCWSTR

A cadeia de caracteres Unicode terminada em nulo que especifica o ADsPath do objeto ADSI. Para obter mais informações e exemplos de código de cadeias de caracteres de associação para esse parâmetro, consulte LDAP ADsPath e WinNT ADsPath.

[in] lpszUserName

Tipo: LPCWSTR

A cadeia de caracteres Unicode terminada em nulo que especifica o nome de usuário a ser fornecido ao serviço de diretório a ser usado para credenciais. Essa cadeia de caracteres sempre deve estar no formato "<domain\><user name>" para evitar ambiguidade. Por exemplo, se DomainA e DomainB tiverem uma relação de confiança e ambos os domínios tiverem um usuário com o nome "user1", não será possível prever qual domínio ADsOpenObject usará para validar "user1".

[in] lpszPassword

Tipo: LPCWSTR

A cadeia de caracteres Unicode terminada em nulo que especifica a senha a ser fornecida ao serviço de diretório a ser usada para credenciais.

[in] dwReserved

Tipo: DWORD

Sinalizadores de autenticação específicos do provedor usados para definir as opções de associação. Para obter mais informações, consulte ADS_AUTHENTICATION_ENUM.

[in] riid

Tipo: REFIID

Identificador de interface para a interface solicitada neste objeto.

[out] ppObject

Tipo: VOID**

Ponteiro para um ponteiro para a interface solicitada.

Retornar valor

Tipo: HRESULT

Esse método dá suporte aos valores de retorno HRESULT padrão, incluindo o seguinte.

Para obter mais informações, consulte Códigos de erro ADSI.

Comentários

Essa função não deve ser usada apenas para validar as credenciais do usuário.

Um cliente C/C++ chama a função auxiliar ADsOpenObject para associar a um objeto ADSI, usando o nome de usuário e a senha fornecidos como credenciais para o serviço de diretório apropriado. Se lpszUsername e lpszPassword forem NULL e ADS_SECURE_AUTHENTICATION estiver definido, ADSI associará ao objeto usando o contexto de segurança do thread de chamada, que é o contexto de segurança da conta de usuário sob a qual o aplicativo está em execução ou da conta de usuário cliente representada pelo thread de chamada.

As credenciais passadas para a função ADsOpenObject são usadas apenas com o objeto específico associado a e não afetam o contexto de segurança do thread de chamada. Isso significa que, no exemplo abaixo, a chamada para ADsOpenObject usará credenciais diferentes da chamada para ADsGetObject.

HRESULT hr;
IADs *padsRoot1;
IADs *padsRoot2;

hr = ADsOpenObject(L"LDAP://rootDSE",
    pwszUsername,
    pwszPassword,
    ADS_SECURE_AUTHENTICATION,
    IID_IADs,
    (LPVOID*)&padsRoot1);

hr = ADsGetObject(L"LDAP://rootDSE",
    IID_IADs,
    (LPVOID*)&padsRoot2);

Para trabalhar com o provedor WinNT: , você pode passar lpszUsername como uma das seguintes cadeias de caracteres:

O nome de uma conta de usuário, ou seja, "jeffsmith".
O nome de usuário estilo Windows, ou seja, "Fabrikam\jeffsmith".

Com o provedor LDAP para Active Directory, você pode passar lpszUsername como uma das seguintes cadeias de caracteres:

O nome de uma conta de usuário, como "jeffsmith". Para usar um nome de usuário por si só, você deve definir apenas o sinalizador ADS_SECURE_AUTHENTICATION no parâmetro dwReserved .
O caminho do usuário de uma versão anterior do Windows, como "Fabrikam\jeffsmith".
Nome diferenciado, como "CN=Jeff Smith,OU=Sales,DC=Fabrikam,DC=Com". Para usar um DN, o parâmetro dwReserved deve ser zero ou deve incluir o sinalizador ADS_USE_SSL .
Nome da entidade de usuário (UPN), como "jeffsmith@Fabrikam.com". Para usar um UPN, atribua o valor UPN apropriado para o atributo userPrincipalName do objeto de usuário de destino.

Se a autenticação Kerberos for necessária para a conclusão bem-sucedida de uma solicitação de diretório específica usando o provedor LDAP, a cadeia de caracteres de associação lpszPathName deverá usar um ADsPath sem servidor, como "LDAP://CN=Jeff Smith,CN=admin,DC=Fabrikam,DC=com", ou deve usar um ADsPath com um nome de servidor DNS totalmente qualificado, como "LDAP://central3.corp.Fabrikam.com/CN=Jeff Smith, CN=admin,DC=Fabrikam,DC=com". A associação ao servidor usando um nome NETBIOS simples ou um nome DNS curto, por exemplo, usando o nome curto "central3" em vez de "central3.corp.Fabrikam.com", pode ou não gerar a autenticação Kerberos.

O exemplo de código a seguir mostra como associar a um objeto de serviço de diretório com as credenciais de usuário solicitadas.

IADs *pObject;
LPWSTR szUsername = NULL;
LPWSTR szPassword = NULL
HRESULT hr;

// Insert code to securely retrieve the user name and password.

hr = ADsOpenObject(L"LDAP://CN=Jeff,DC=Fabrikam,DC=com",
                   "jeffsmith",
                   "etercespot",
                   ADS_SECURE_AUTHENTICATION, 
                   IID_IADs,
                   (void**) &pObject);

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista
Servidor mínimo com suporte	Windows Server 2008
Plataforma de Destino	Windows
Cabeçalho	adshlp.h
Biblioteca	Activeds.lib
DLL	Activeds.dll