estrutura BIND_OPTS2 (objidl.h)

Artigo
08/25/2023

Contém parâmetros usados durante uma operação de associação de moniker.

Sintaxe

typedef struct tagBIND_OPTS2 {
  DWORD        cbStruct;
  DWORD        grfFlags;
  DWORD        grfMode;
  DWORD        dwTickCountDeadline;
  DWORD        dwTrackFlags;
  DWORD        dwClassContext;
  LCID         locale;
  COSERVERINFO *pServerInfo;
} BIND_OPTS2, *LPBIND_OPTS2;

Membros

cbStruct

O tamanho dessa estrutura, em bytes.

grfFlags

Sinalizadores que controlam aspectos das operações de associação de moniker. Esse valor é qualquer combinação dos sinalizadores de bits na enumeração BIND_FLAGS . A função CreateBindCtx inicializa esse membro como zero.

grfMode

Sinalizadores que devem ser usados ao abrir o arquivo que contém o objeto identificado pelo moniker. Os valores possíveis são as constantes STGM. A operação de associação usa esses sinalizadores na chamada para IPersistFile::Load ao carregar o arquivo. Se o objeto já estiver em execução, esses sinalizadores serão ignorados pela operação de associação. A função CreateBindCtx inicializa esse campo para STGM_READWRITE.

dwTickCountDeadline

A hora do relógio pela qual o chamador gostaria que a operação de associação fosse concluída, em milissegundos. Esse membro permite que o chamador limite o tempo de execução de uma operação quando a velocidade é de importância primária. Um valor zero indica que não há data limite. Os chamadores geralmente usam essa funcionalidade ao chamar o método IMoniker::GetTimeOfLastChange , embora ele também possa ser aplicado a outras operações. A função CreateBindCtx inicializa esse campo como zero.

Os prazos típicos permitem algumas centenas de milissegundos de execução. Esse prazo é uma recomendação, não um requisito; no entanto, as operações que excedem o prazo em uma grande quantidade podem causar atrasos para o usuário final. Cada implementação de moniker deve tentar concluir sua operação até o prazo final ou falhar com o erro MK_E_EXCEEDEDDEADLINE.

Se uma operação de associação exceder a data limite porque um ou mais objetos necessários não estão em execução, a implementação do moniker deverá registrar os objetos responsáveis no contexto de associação usando iBindCtx::RegisterObjectParam. Os objetos devem ser registrados sob os nomes de parâmetro "ExceededDeadline", "ExceededDeadline1", "ExceededDeadline2" e assim por diante. Se o chamador encontrar posteriormente o objeto na tabela de objetos em execução, o chamador poderá repetir a operação de associação.

A função GetTickCount indica o número de milissegundos desde a inicialização do sistema e é encapsulada novamente para zero após 2^31 milissegundos. Consequentemente, os chamadores devem ter cuidado para não passar inadvertidamente um valor zero (o que indica que não há prazo) e as implementações de moniker devem estar cientes dos problemas de encapsulamento do relógio.

dwTrackFlags

Um moniker pode usar esse valor durante o acompanhamento de link. Se os dados persistentes originais que o moniker está referenciando tiverem sido movidos, o moniker poderá tentar restabelecer o link pesquisando os dados originais por meio de algum mecanismo adequado. Esse membro fornece informações adicionais sobre como o link deve ser resolvido. Consulte a documentação do parâmetro fFlags em IShellLink::Resolve.

A implementação do moniker de arquivo COM usa o mecanismo de link do shell para restabelecer links e passa esses sinalizadores para IShellLink::Resolve.

dwClassContext

O contexto de classe, obtido da enumeração CLSCTX , que deve ser usado para instanciar o objeto. Os monikers normalmente passam esse valor para o parâmetro dwClsContext de CoCreateInstance.

locale

O valor LCID que indica a preferência do cliente para a localidade a ser usada pelo objeto ao qual eles estão associando. Um moniker passa esse valor para IClassActivator::GetClassObject.

pServerInfo

Um ponteiro para uma estrutura COSERVERINFO . Esse membro permite que os clientes que chamam IMoniker::BindToObject especifiquem informações do servidor. Os clientes podem passar uma estrutura BIND_OPTS2 para o método IBindCtx::SetBindOptions . Se um nome de servidor for especificado na estrutura COSERVERINFO , a associação de moniker será encaminhada para o computador especificado. SetBindOptions copia apenas os membros do struct de BIND_OPTS2, não a estrutura COSERVERINFO e os ponteiros que ele contém. Os chamadores podem não liberar nenhum desses ponteiros até que o contexto de associação seja liberado. Atualmente, o novo moniker de classe do COM não respeita o sinalizador pServerInfo .

Comentários

Uma estrutura BIND_OPTS2 é armazenada em um contexto de associação; o mesmo contexto de associação é usado por cada componente de um moniker composto durante a associação, permitindo que os mesmos parâmetros sejam passados para todos os componentes de um moniker composto. Consulte IBindCtx para obter mais informações sobre contextos de associação.

Os clientes Moniker (usam um moniker para adquirir um ponteiro de interface para um objeto) normalmente não precisam especificar valores para os membros dessa estrutura. A função CreateBindCtx cria um contexto de associação com as opções de associação definidas como valores padrão adequados para a maioria das situações; A função BindMoniker faz a mesma coisa ao criar um contexto de associação para uso na associação de um moniker. Se você quiser modificar os valores dessas opções de associação, poderá fazer isso passando uma estrutura BIND_OPTS2 para o método IBindCtx::SetBindOptions . Os implementadores do Moniker podem passar uma estrutura BIND_OPTS2 para o método IBindCtx::GetBindOptions para recuperar os valores dessas opções de associação.