Estrutura LDAPVLVInfo (winldap.h)

Artigo
08/27/2023

A estrutura LDAPVLVInfo é usada para configurar os parâmetros de pesquisa para um controle de solicitação de VLV (exibição de lista virtual) (LDAP_CONTROL_VLVREQUEST).

A estrutura LDAPVLVInfo também pode ser usada por aplicativos para gerenciar os dados de estado associados a uma série de interações de cliente/servidor VLV.

Sintaxe

typedef struct ldapvlvinfo {
  int     ldvlv_version;
  ULONG   ldvlv_before_count;
  ULONG   ldvlv_after_count;
  ULONG   ldvlv_offset;
  ULONG   ldvlv_count;
  PBERVAL ldvlv_attrvalue;
  PBERVAL ldvlv_context;
  VOID    *ldvlv_extradata;
} LDAPVLVInfo, *PLDAPVLVInfo;

Membros

ldvlv_version

Identifica a versão da estrutura LDAPVLVInfo . Isso sempre deve ser definido como o valor LDAP_VLVINFO_VERSION (1).

ldvlv_before_count

Identifica o número de entradas antes da entrada de destino que o cliente deseja que o servidor envie de volta nos resultados da lista. Esse campo corresponde ao elemento beforeCount do controle LDAP_CONTROL_VLVREQUEST codificado em BER.

ldvlv_after_count

Indica o número de entradas após a entrada de destino que o cliente instrui o servidor a enviar de volta nos resultados da lista. Esse campo corresponde ao elemento afterCount do controle LDAP_CONTROL_VLVREQUEST codificado em BER.

ldvlv_offset

Indica uma taxa entre o valor de deslocamento e a contagem de conteúdo. Por exemplo, considere se um usuário arrasta a barra de rolagem para exibir entradas no meio da lista. Se o cliente estimar que a lista inteira contém 100 entradas, para exibir a lista intermediária, ele calculará o deslocamento como 50, para que o cliente envie esse valor de deslocamento, com 100 como a contagem de conteúdo, enviado no membro ldvlv_count , para o servidor. Quando o servidor recebe esses dados, ele pode ter calculado a contagem de conteúdo como 500, portanto, calcula o deslocamento para localizar o destino solicitado pelo cliente, usando a seguinte fórmula:

Si = Sc * (Ci/Cc)

onde

Si é o deslocamento de lista real usado pelo servidor

Sc é a estimativa do servidor para contagem de conteúdo

Ci é o deslocamento enviado pelo cliente

Cc é a contagem de conteúdo enviada pelo cliente

Se o cliente usar um valor de deslocamento de um (1), ele indicará que o destino é a primeira entrada na lista. Se o cliente usar um valor de deslocamento igual a ldvlv_count, o item será a última entrada na lista. O deslocamento será igual a zero (0) quando ldvlv_count for igual a zero, que seria a última entrada na lista.

Os deslocamentos serão usados somente se a pesquisa não for baseada em um valor de atributo, portanto , ldvlv_attrvalue deve ser NULL. Esse campo corresponde ao elemento offset dentro do controle LDAP_CONTROL_VLVREQUEST codificado em BER.

ldvlv_count

Indica a contagem de conteúdo da lista. Uma estimativa da contagem de conteúdo é enviada pelo cliente ao servidor ao enviar uma solicitação de pesquisa, a fim de permitir que o servidor calcule um valor de deslocamento. O servidor retorna seu próprio cálculo da contagem de conteúdo para o cliente em sua resposta. Se o cliente não tiver uma estimativa para a contagem de conteúdo, ele enviará zero (0), o que indica que o servidor deve usar sua própria estimativa para contagem de conteúdo. Esse membro é usado com ldvlv_offset. Como a contagem de conteúdo é necessária somente se a pesquisa não for baseada em um valor de atributo, o membro ldvlv_attrvalue deverá ser NULL. Esse campo corresponde ao elemento contentCount dentro do controle LDAP_CONTROL_VLVREQUEST codificado por BER e ao elemento contentCount dentro do controle LDAP_CONTROL_VLVRESPONSE codificado em BER.

ldvlv_attrvalue

Fornece um valor de atributo como uma entrada de destino para a pesquisa. O servidor compara esse membro a valores que têm o mesmo tipo de atributo, conforme especificado no membro sk_attrtype da estrutura LDAPSortKey . Se um deslocamento for usado, esse membro deverá ser NULL. Esse membro corresponde ao elemento assertionValue do controle LDAP_CONTROL_VLVREQUEST codificado em BER.

ldvlv_context

Fornece a ID de contexto atribuída pelo servidor para identificar essa operação de pesquisa. Esse é um "cookie" opaco usado pelo servidor para manter o controle interno da operação VLV atual. Na primeira chamada para a operação de pesquisa usando o controle VLV, esse parâmetro deve ser definido como NULL. O servidor pode retornar um valor na mensagem LDAP_CONTROL_VLVRESPONSE . Esse valor de "cookie" deve ser retornado ao servidor na próxima chamada para uma função de pesquisa que é executada em uma lista de VLV específica.

ldvlv_extradata

Esse campo é reservado para uso específico do aplicativo e não é usado pela função ldap_create_vlv_control ; não tem nenhum efeito sobre o controle que é criado.

Comentários

Há dois métodos para calcular o destino de uma pesquisa VLV: usar um valor de atributo ou usar um deslocamento. Elementos diferentes dessa estrutura serão usados dependendo de qual tipo de pesquisa você escolher. Ambos os métodos exigem que os valores sejam inseridos para os membros ldvlv_before_count e ldvlv_after_count . Especifique uma contagem de conteúdo de lista em ldvlv_count ou, se você não souber esse valor, use zero (0) para que o servidor o calcule.

Pesquisando com valores de atributo
Para executar uma pesquisa baseada em valor, por exemplo, se você quiser pesquisar Jeff Smith e souber o tipo de atributo desse valor, defina o tipo de atributo no membro sk_attrtype da estrutura LDAPSortKey e o valor do atributo em ldvlv_attrvalue. O membro ldvlv_offset é ignorado para esse tipo de pesquisa, portanto, não é necessário defini-lo.

Por exemplo, para executar uma pesquisa usando a letra J. Para recuperar 20 resultados, defina ldvlv_before_count como 9, ldvlv_after_count como 10 e ldvlv_attrvalue como J. O servidor localiza a primeira entrada na lista que não é menor que J, como Jeff Smith, e retorna as nove entradas anteriores, a entrada de destino e as 10 entradas em andamento. O servidor retornaria um ldvlv_count de 30000 e um ldvlv_offset de 4053 no controle LDAP_CONTROL_VLVRESPONSE ; que está supondo que Jeff Smith é o número de entrada 4053 na lista. O servidor poderá retornar poucas entradas do que o solicitado antes e/ou após a entrada de destino se não houver entradas suficientes na lista para atender à solicitação. Por exemplo, se houvesse apenas duas entradas no total antes da primeira entrada 'J', o servidor não poderia retornar nove entradas anteriores.
Pesquisando com deslocamentos
Para usar deslocamentos para sua pesquisa, defina um deslocamento em ldvlv_offset e defina ldvlv_attrvalue como NULL. Defina também o tipo de atributo no membro sk_attrtype da LDAPSortKey, mas, desta vez, o destino será um deslocamento dentro da lista de entradas para esse tipo de atributo, em vez de um valor de atributo específico.

Por exemplo, para direcionar a pesquisa para 68% da lista de resultados da pesquisa. Se o ldvlv_count for 30000, o 68% de 30000 será 20400. Para recuperar 20 resultados, defina ldvlv_before_count como 9, ldvlv_after_count como 10, ldvlv_count como 30000, ldvlv_offset como 20400 e envie a solicitação para o servidor. O servidor retorna as 20 entradas anteriores na lista, além do ldvlv_count de 30000 e um ldvlv_offset de 20400. Lembre-se de que é possível que o número de entradas na lista altere entre a estimativa do cliente do número de entradas e o servidor que processa a pesquisa, o que, por sua vez, afeta os deslocamentos. Nesse caso, a entrada de destino retornada pode não ser exatamente a entrada de destino que o cliente esperava. Os aplicativos devem estar preparados para lidar com essa incerteza.

Lembre-se de que um controle de classificação deve acompanhar uma solicitação de pesquisa VLV para especificar a lista ordenada de entradas na qual a pesquisa VLV é executada. Os servidores podem rejeitar pesquisas VLV executadas em listas para as quais não têm índices.