atributo byte_count
O atributo ACF [byte_count] é um atributo de parâmetro que associa um tamanho, em bytes, à área de memória indicada pelo ponteiro.
[ function-attribute-list ] function-name(
[byte_count(length-variable-name)] parameter-name);
...);
Parâmetros
-
function-attribute-list
-
Especifica zero ou mais atributos de função ACF.
-
function-name
-
Especifica o nome da função definida no arquivo IDL. O nome da função é necessário.
-
length-variable-name
-
Especifica o nome do parâmetro [in]-only que especifica o tamanho, em bytes, da área de memória referenciada por parameter-name.
-
parameter-name
-
Especifica o nome do parâmetro de ponteiro [out]-only definido no arquivo IDL.
Comentários
O atributo ACF [byte_count] representa uma extensão da Microsoft para a IDL do DCE. Portanto, esse atributo não está disponível quando você usa a opção /osf do compilador MIDL.
Observação
O atributo [contagem de bytes] não tem mais suporte na sintaxe NDR64 devido à dificuldade em estimar o tamanho necessário para todos os parâmetros [out ].
A memória referenciada pelo parâmetro de ponteiro é contígua e não é alocada ou liberada pelos stubs do cliente. Esse recurso do atributo [byte_count] permite criar uma área de buffer persistente na memória do cliente que pode ser reutilizado durante mais de uma chamada para o procedimento remoto.
A capacidade de desativar a alocação de memória de stub do cliente permite ajustar o aplicativo para obter eficiência. Por exemplo, o atributo [byte_count] pode ser usado por funções de provedor de serviços que usam o Microsoft RPC. Quando um aplicativo de usuário chama a API do provedor de serviços e envia um ponteiro para um buffer, o provedor de serviços pode passar o ponteiro do buffer para a função remota. O provedor de serviços pode reutilizar o buffer durante várias chamadas remotas sem forçar o usuário a realocar a área de memória.
A área de memória pode conter estruturas de dados complexas que consistem em vários ponteiros. Como a área de memória é contígua, o aplicativo não precisa fazer várias chamadas para liberar individualmente cada ponteiro e estrutura. Em vez disso, ele pode alocar ou liberar a área de memória com uma chamada para a alocação de memória ou rotina livre.
O buffer deve ser um parâmetro [out]-only, enquanto o comprimento do buffer em bytes deve ser um parâmetro [in]-only.
Especifique um buffer grande o suficiente para conter todos os parâmetros [out ]. Devido ao preenchimento oculto, use superestimações em vez de contagens exatas. Por exemplo, ponteiros de 4 bytes não sãomarsalizados em um limite alinhado de 4 bytes em plataformas de 32 bits e ponteiros de 8 bytes em um limite de 8 bytes em plataformas de 64 bits. Portanto, o preenchimento de alinhamento que os stubs executarão deve ser contabilizado no espaço do buffer. Além disso, os níveis de empacotamento usados durante a compilação da linguagem C podem variar. Use um valor de contagem de bytes que contabilize bytes de empacotamento adicionais adicionados para o nível de empacotamento usado durante a compilação da linguagem C. Uma prática segura que abrange plataformas de 32 bits e plataformas de 64 bits é assumir que cada objeto que entra no bloco de memória grande começa em um endereço que é um múltiplo de 8.
Exemplos
/* IDL file */
HRESULT proc1([in] unsigned long length,
[out] struct my_struct * pMyStruct);
/* ACF file */
proc1([byte_count(length)] pMyStruct);
Confira também