Convenções de codificação para metadados API
Este tópico discute as convenções de codificação usadas pelos metadados API.
Manipulação de parâmetros de string
Os metadados API expõe todas as seqüências de caracteres no formato Unicode. (O formato no disco para nomes de símbolo é na verdade, UTF-8, mas que está oculto de clientes de API de metadados.) Cada seqüência de caracteres retornada é um triplo de três parâmetros (nomes de parâmetro real variam):
[in] ULONG cchString - The size, in bytes, of the buffer in which the string, including the terminating null character, is to be returned.
[out] LPCWSTR wzString - A pointer to the buffer in which the string is returned.
[out] ULONG *pchString - Um ponteiro para o dimensionar da seqüência de caracteres retornada (incluindo o caractere nulo de terminação). Se o buffer é muito pequeno para armazenar a seqüência completa, a seqüência de caracteres retornada é truncada, uma indicação de erro é retornada e o cliente pode realocar o buffer e tente novamente se desejar.
Nomes de símbolo
As seguintes convenções aplicar para nomes de símbolo para parâmetros de seqüência de caracteres:
String parâmetros que são nomes de símbolos são sempre considerados terminada com caractere nulo e não necessária parâmetro [in] comprimento. Não há suporte para caracteres nulo incorporados.
Se um [no] seqüência de parâmetros é muito grande para persistir sem truncamento, um erro será retornado.
Strings de usuário
As seguintes convenções se aplicam aos parâmetros de cadeia de caracteres fornecido pelo usuário:
Seqüências de usuário podem ter incorporados caracteres nulos e não devem ter um terminador nulo.
Um comprimento deve ser fornecido no cchString parâmetro. O dimensionar do buffer deve ser exatamente o comprimento da seqüência de caracteres que será armazenado.
Armazenando valores padrão
Constantes podem ser armazenados em metadados sistema autônomo valores padrão para campos, parâmetros e propriedades. Três parâmetros são usados para especificar uma constante (parâmetro real nomes variar):
[in] DWORD dwCPlusTypeFlag - A value of the CorElementType enumeration that specifies the type of the default value.
[no] void const *pValue -Um ponteiro para o valor padrão real. Por exemplo, um ponteiro para o de 4 byte DWORD manter 0x0000002A armazenará um DWORD valor de 42 decimal nos metadados. O tipo (especificado em dwCPlusTypeFlag) do padrão o valor está limitado a um primitivo ou uma seqüência de caracteres. If dwCPlusTypeFlag ELEMENT_TYPE_CLASS, é o valor padrão será nulo.
[in] ULONG cchValue - The number of Unicode characters in the byte sequence to which pValue points. Isso é necessário apenas se o tipo especificado em dwCPlusTypeFlag, é ELEMENT_TYPE_STRING. Em outros casos, o comprimento é inferido do tipo.
Valores padrão não são automaticamente inseridos no código de inicialização ou em áreas de dados estaticamente inicializados. Eles simplesmente são registrados no metadados.
Para indicar que não deseja especificar um valor padrão, conjunto todos os bits de dwCPlusTypeFlag (isto é, conjunto o valor como -1).
Ponteiros nulo para devolução Parameters
Como os metadados APIs fazer um mínimo de verificação de erros, esperam um ponteiro nulo para retorno parâmetros nas seguintes circunstâncias:
In Define métodos, é necessário para o token retornado um ponteiro nulo. Esses métodos criam o item a ser definido e retornar um token para o item. Você pode optar por descartar o token se não precisar dela.
Find métodos sempre retornam o token para o item se ele for encontrado com êxito.
In Get métodos, você pode passar nulo nos parâmetros que você não precisa back.
In Set métodos, geralmente não há nenhum valor retornado. Passar no token para o item seja atualizada juntamente com os valores para atualizar e esses métodos de executam a atualização.
Valores de parâmetro a ser ignorado
Vários métodos nos metadados do API permitem alterar as propriedades de um item que foi definido anteriormente. O exemplo a seguir utiliza o IMetaDataEmit::SetFieldProps método para alterar propriedades do campo, que foram previamente fornecidas em uma telefonar para IMetaDataEmit::DefineField:
HRESULT SetFieldProps(mdFieldDef fd, DWORD dwFieldFlags,
DWORD dwDefType, void const *pValue, ULONG cchValue)
Às vezes, convém alterar dwFieldFlags mas não pValue (ou vice-versa). Nesse caso, você deve passar um valor de parâmetro para evitar um erro, mesmo se desejar alterar esse valor. No entanto, você pode passar um valor específico que designa o argumento deve ser ignorado se desejar alterar seu valor. Os metadados APIs usam as seguintes convenções para indicar que um argumento de método deve ser ignorado:
Se o parâmetro é um tipo de ponteiro, passar um ponteiro nulo.
Se o parâmetro é um tipo de valor (normalmente uma bitmask sinalizadores), passe um valor de todos os bits definidos (– 1).
Erro de retorno
Quase todos os métodos no IMetaDataDispenserEx, IMetaDataEmit, and IMetaDataImport interfaces retornam um valor HRESULT para indicar seu resultado. Isso tem o valor S_OK se a operação foi bem-sucedida. Se a telefonar não for bem-sucedida, ele retorna outro valor para descrever o motivo pelo qual a operação falhou.
Um padrão geral em todos sistema autônomo metadados que APIs é que, se o chamador fornece um buffer de cadeia de caracteres é muito pequeno para conter sistema autônomo resultados, sistema autônomo APIs copiar sistema autônomo número de caracteres sistema autônomo irá caber, mas retornar o valor CLDB_S_TRUNCATION em vez de S_OK HRESULT.
Chamadores do IMetadata as interfaces são compiladores ou ferramentas. É importante que esses chamadores sempre verificar o status de retorno de cada telefonar para detectar erros. Nesses casos, sistema autônomo condições de erro refletem um problema do chamador direto (sistema autônomo um compilador) em vez do usuário (sistema autônomo um programa aplicativo).
Gerenciamento de memória
O padrão COM genérico é que o chamador libera a memória que aloca o computador chamado. No entanto, os métodos de metadados operam de forma diferente.
Retornam vários métodos de metadados [out] ponteiros para blocos de memória. Se a memória é parte da heap de metadados do módulo e pertence o common linguagem tempo de execução (CLR). Portanto, você terá um ponteiro diretamente para armazenar na memória do CLR os metadados e seu aplicativo não é necessário para liberar a memória.
Suporte genéricos
No .NET estrutura versão 2.0, os metadados APIs foram estendidas significativamente para oferecer suporte a genéricos (às vezes também chamados de "polimorfismo paramétrico"). Os genéricos são um pouco semelhantes aos modelos C++. Um exemplo de definição de um clsistema autônomos genérico em translation from VPE for Csharp pode ser sistema autônomo segue:
public class Dictionary<Key, Val> { . . . }
Nesse caso, a Dictionary classe é parametrizada com dois parâmetros genéricos chamados Key e Val. Quando a classe é instanciada, o usuário seleciona tipos para sistema autônomo parâmetros genéricos, sistema autônomo no exemplo a seguir:
Dictionary<string, int> NameToPhone = new Dictionary<string, int>();
Dictionary<int, string> PhoneToName = new Dictionary<int, string>();