atributo context_handle
El atributo [context_handle] identifica un identificador de enlace que mantiene el contexto o la información de estado en el servidor entre llamadas a procedimiento remoto.
typedef [context_handle [ , type-attribute-list ] ] type-specifier declarator-list;
[context_handle [, function-attr-list ] ] type-specifier [ptr-decl] function-name(
[ [parameter-attribute-list] ] type-specifier [declarator], ...);
[ [ function-attr-list ] ] type-specifier [ ptr-decl ] function-name(
[context_handle [ , parameter-attribute-list ] ] type-specifier [declarator], ...);
[ void __RPC_USER context-handle-type_rundown (
context-handle-type); ]
Parámetros
-
type-attribute-list
-
Especifica uno o varios atributos que se aplican al tipo.
-
type-specifier
-
Especifica un tipo de puntero 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. El declarador de un identificador de contexto debe incluir al menos un declarador de puntero. Para obtener más información, vea Array and Sized-Pointer Attributes, arrays, and Arrays and Pointers. La lista de declaradores consta de uno o varios declaradores, separados por comas. El identificador parameter-name del declarador de función es opcional.
-
function-attr-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 cero o más declaradores de puntero. Un declarador de puntero es el mismo que el declarador de puntero usado en C; se construye a partir del * designador, modificadores como lejos y el calificador const.
-
nombre de función
-
Especifica el nombre del procedimiento remoto.
-
parameter-attribute-list
-
Especifica cero o más atributos direccionales, atributos de campo, atributos de uso y atributos de puntero adecuados para el tipo de parámetro especificado. Separe varios atributos con comas.
-
context-handle-type
-
Especifica el identificador que especifica el tipo de identificador de contexto tal como se define en una declaración typedef que toma el atributo [context_handle]. La rutina de desatención es opcional.
Windows Server 2003 y Windows XP: Una sola interfaz puede dar cabida a los identificadores de contexto serializados y no serializados, lo que permite que un método en una interfaz tenga acceso exclusivamente a un identificador de contexto (serializado), mientras que otros métodos acceden a ese controlador de contexto en modo compartido (no serializado). Estas funcionalidades de acceso son comparables a los mecanismos de bloqueo de lectura y escritura; los métodos que usan un identificador de contexto serializado son usuarios exclusivos (escritores), mientras que los métodos que usan un identificador de contexto no serializado son usuarios compartidos (lectores). Los métodos que destruyen o modifican el estado de un identificador de contexto deben serializarse. Los métodos que no modifican el estado de un controlador de contexto, como los métodos que simplemente leen de un identificador de contexto, se pueden norializar. Tenga en cuenta que los métodos de creación se serializan implícitamente.
Observaciones
El atributo [context_handle] puede aparecer como atributo de tipo typedef IDL, como atributo de tipo de valor devuelto de función o como atributo de parámetro. Al aplicar el atributo [context_handle] a una definición de tipo, también debe proporcionar una rutina de resumen de contexto. Consulte Rutina de ejecución del contexto del servidor para obtener más información.
Cuando se usa el compilador MIDL en modo predeterminado (/ms_ext), un identificador de contexto puede ser cualquier tipo de puntero seleccionado por el usuario, siempre y cuando cumpla los requisitos para los identificadores de contexto descritos aquí. Los datos asociados a este tipo de controlador de contexto no se transmiten en la red y solo la aplicación de servidor debe manipularlos. Los compiladores IDL de DCE restringen los identificadores de contexto a punteros de tipo void*. Por lo tanto, esta característica no está disponible cuando se usa el modificador /osf del compilador MIDL.
Al igual que con otros tipos de identificadores, el identificador de contexto es opaco para la aplicación cliente y los datos asociados a él no se transmiten. En el servidor, el identificador de contexto actúa como identificador en el contexto activo y se puede acceder a todos los datos asociados al tipo de identificador de contexto.
Para crear un identificador de contexto, el cliente pasa al servidor un puntero [out], [ref] a un identificador de contexto. (El propio identificador de contexto puede tener un valor NULL o distinto de NULL , siempre que su valor sea coherente con sus atributos de puntero. Por ejemplo, cuando el tipo de identificador de contexto tiene aplicado el atributo [ref], no puede tener un valor NULL ). Se debe proporcionar otro identificador de enlace para realizar el enlace hasta que se cree el identificador de contexto. Cuando no se especifica ningún identificador explícito, se usa el enlace implícito. Cuando no hay ningún atributo [implicit_handle] presente, se usa un identificador automático.
El procedimiento remoto en el servidor crea un identificador de contexto activo. El cliente debe usar ese identificador de contexto como un parámetro [in] o [in, out] en llamadas posteriores. Un identificador de contexto [in]-only se puede usar como identificador de enlace, por lo que debe tener un valor distinto de NULL . Un identificador de contexto [in]-only no refleja los cambios de estado en el servidor.
En el servidor, el procedimiento llamado puede interpretar el identificador de contexto según sea necesario. Por ejemplo, el procedimiento llamado puede asignar almacenamiento del montón y usar el identificador de contexto como puntero a este almacenamiento.
Para cerrar un identificador de contexto, el cliente pasa el identificador de contexto como un argumento [in], [out]. El servidor debe devolver un identificador de contexto NULL cuando ya no mantiene el contexto en nombre del autor de la llamada. Por ejemplo, si el identificador de contexto representa un archivo abierto y la llamada cierra el archivo, el servidor debe establecer el identificador de contexto en NULL y devolverlo al cliente. Un valor NULL no es válido como identificador de enlace en las llamadas posteriores.
Un identificador de contexto solo es válido para un servidor. Cuando una función tiene dos parámetros de identificador y el identificador de contexto no es NULL, los identificadores de enlace deben hacer referencia al mismo espacio de direcciones.
Cuando una función tiene un identificador de contexto [in] o [in, out] , su identificador de contexto se puede usar como identificador de enlace. En este caso, no se usa el enlace implícito y se omite el atributo [implicit_handle] o [auto_handle].
Las restricciones siguientes se aplican a los identificadores de contexto:
- Los identificadores de contexto no pueden ser elementos de matriz, miembros de estructura ni miembros de unión. Solo pueden ser parámetros.
- Los identificadores de contexto no pueden tener el atributo [transmit_as] ni [represent_as].
- Los parámetros que son punteros a los identificadores de contexto [out] deben ser punteros [ref].
- Un identificador de contexto [in] se puede usar como identificador de enlace y no puede ser NULL.
- Un identificador de contexto [in, out context puede ser NULL en la entrada, pero solo si el procedimiento tiene otro parámetro de identificador explícito. Si no hay ningún otro parámetro de controlador de contexto explícito que no sea NULL , el identificador de contexto [in, out] no puede ser NULL.
- No se puede usar un identificador de contexto con devoluciones de llamada.
Ejemplos
typedef [context_handle] void * PCONTEXT_HANDLE_TYPE;
short RemoteFunc1([out] PCONTEXT_HANDLE_TYPE * pCxHandle);
short RemoteFunc2([in, out] PCONTEXT_HANDLE_TYPE * pCxHandle);
void __RPC_USER PCONTEXT_HANDLE_TYPE_rundown (PCONTEXT_HANDLE_TYPE);
Vea también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de