unique (atributo)
El atributo [unique] especifica un puntero único.
pointer_default(unique)
typedef [ unique [[ , type-attribute-list ]] ] type-specifier declarator-list;
typedef struct-or-union-declarator
{
[ unique [[ , field-attribute-list ]] ] type-specifier declarator-list;
...}
[ unique [[ , function-attribute-list ]] ] type-specifier ptr-decl function-name(
[[ [ parameter-attribute-list ] ]] type-specifier [[declarator]]
, ...);
[[ [ function-attribute-list ] ]] type-specifier [[ptr-decl]] function-name(
[ unique [[ , parameter-attribute-list ]] ] type-specifier [[declarator]]
, ...);
-
type-attribute-list
-
Especifica uno o varios atributos que se aplican al tipo. Los atributos de tipo válidos incluyen [handle], [switch_type], [transmit_as]; el atributo de puntero [ref], [unique], o [ptr]; y los atributos de uso [context_handle], [string] y [ignore]. Separe varios atributos con comas.
-
type-specifier
-
Especifica un tipo base, una estructura, una unión, un tipo de enumeración o un identificador de tipo. Una especificación de almacenamiento opcional puede preceder al especificador de tipos.
-
declarator y declarator-list
-
Especifica declaradores de C estándar, como identificadores, declaradores de puntero y declaradores de matriz. Para obtener más información, vea Array and Sized-Pointer Attributes, arrays., and Arrays and Pointers. La lista declarator consta de uno o varios declaradores separados por comas. El identificador parameter-name del declarador de función es opcional.
-
struct-or-union-declarator
-
Especifica un declarador de unión o struct MIDL.
-
field-attribute-list
-
Especifica cero o más atributos de campo que se aplican al miembro de estructura, al miembro de unión o al parámetro de función. Los atributos de campo válidos incluyen [first_is], [last_is], [length_is], [max_is], [size_is]; los atributos de uso [string], [ignore]y [context_handle]; el atributo de puntero [ref], [unique], o [ptr]; y el atributo de unión [switch_type]. Separe varios atributos de campo con comas.
-
function-attribute-list
-
Especifica cero o más atributos que se aplican a la función. Los atributos de función válidos son [devolución de llamada], [local]; el atributo de puntero [ref], [unique], o [ptr]; y los atributos de uso [string], [ignore]y [context_handle].
-
ptr-decl
-
Especifica al menos un declarador de puntero al que se aplica el atributo [unique]. Un declarador de puntero es el mismo que el declarador de puntero utilizado en C; se construye a partir del designador * , modificadores como far y el calificador const.
-
function-name
-
Especifica el nombre del procedimiento remoto.
-
parameter-attribute-list
-
Consta de cero o más atributos adecuados para el tipo de parámetro especificado. Los atributos de parámetro pueden tomar los atributos direccionales [in] y [out]; los atributos de campo [first_is], [last_is], [length_is], [max_is], [size_is], y [switch_type]; el atributo de puntero [ref], unique o ptr; y los atributos de uso [context_handle] y [string]. El atributo de uso [ignore] no se puede usar como atributo de parámetro. Separe varios atributos con comas.
Los atributos de puntero se pueden aplicar como un atributo de tipo; como atributo de campo que se aplica a un miembro de estructura, miembro de unión o parámetro; o como atributo de función que se aplica al tipo de valor devuelto de función. El atributo de puntero también puede aparecer con la palabra clave [pointer_default].
Un puntero único tiene las siguientes características:
- Puede tener el valor NULL.
- Puede cambiar durante una llamada de NULL a no NULL, de un valor distinto de NULL a NULL, o de un valor distinto de NULL a otro.
- Puede asignar memoria nueva en el cliente. Cuando el puntero único cambia de NULL a no NULL, los datos devueltos desde el servidor se escriben en un nuevo almacenamiento.
- Puede usar la memoria existente en el cliente sin asignar memoria nueva. Cuando un puntero único cambia durante una llamada de un valor distinto de NULL a otro, se supone que el puntero apunta a un objeto de datos del mismo tipo. Los datos devueltos desde el servidor se escriben en el almacenamiento existente especificado por el valor del puntero único antes de la llamada.
- Puede memoria huérfana en el cliente. Es posible que nunca se libere la memoria a la que hace referencia un puntero único distinto de NULL si el puntero único cambia a NULL durante una llamada y el cliente no tiene otro medio para desreferenciar el almacenamiento.
- No provoca el alias. Al igual que el almacenamiento al que apunta un puntero de referencia, no se puede acceder al almacenamiento al que apunta un puntero único desde cualquier otro nombre de la función.
Los códigos auxiliares llaman a las funciones de administración de memoria proporcionadas por el usuario midl_user_allocate y midl_user_free para asignar y desasignar memoria necesaria para punteros únicos y sus referencias.
Las restricciones siguientes se aplican a punteros únicos:
- El atributo [unique] no se puede aplicar a los parámetros binding-handle ( handle_t) ni a los parámetros de identificador de contexto.
- El atributo [unique] no se puede aplicar a los parámetros de puntero de nivel superior [out]-only (parámetros que solo tienen el atributo direccional [out] ).
- De forma predeterminada, los punteros de nivel superior de las listas de parámetros son punteros [ref]. Esto es true incluso si la interfaz especifica pointer_default(unique). Los parámetros de nivel superior de las listas de parámetros deben especificarse con el atributo [unique] para que sea un puntero único.
- No se pueden usar punteros únicos para describir el tamaño de una matriz o un brazo de unión porque los punteros únicos pueden tener el valor NULL. Esta restricción evita el error que se produce si se usa un valor NULL como tamaño de matriz o el tamaño del brazo de unión.
pointer_default(unique)
typedef [unique, string] unsigned char * MY_STRING_TYPE;
[unique] char * MyFunction([in, out, unique] long * plNumber);