Método IRunningObjectTable::Register (objidl.h)

  • Artículo

Registra un objeto y su moniker de identificación en la tabla de objetos en ejecución (ROT).

Sintaxis

HRESULT Register(
  [in]  DWORD    grfFlags,
  [in]  IUnknown *punkObject,
  [in]  IMoniker *pmkObjectName,
  [out] DWORD    *pdwRegister
);

Parámetros

[in] grfFlags

Especifica si la referencia de ROT a punkObject es débil o fuerte y controla el acceso al objeto a través de su entrada en el ROT. Para obtener más detalles al respecto, consulte la sección Comentarios.

Valor Significado
ROTFLAGS_REGISTRATIONKEEPSALIVE
 Cuando se establece, indica un registro seguro para el objeto .
ROTFLAGS_ALLOWANYCLIENT
 Cuando se establece, cualquier cliente puede conectarse al objeto en ejecución a través de su entrada en rot. Cuando no se establece, solo los clientes de la estación de ventanas que registraron el objeto pueden conectarse a él.

[in] punkObject

Puntero al objeto que se está registrando como en ejecución.

[in] pmkObjectName

Puntero al moniker que identifica punkObject.

[out] pdwRegister

Identificador de esta entrada ROT que se puede usar en llamadas posteriores a IRunningObjectTable::Revoke o IRunningObjectTable::NoteChangeTime. El autor de la llamada no puede especificar NULL para este parámetro. Si se produce un error, *pdwRegister se establece en cero.

Valor devuelto

Este método puede devolver los valores devueltos estándar E_INVALIDARG y E_OUTOFMEMORY, así como los siguientes valores.

Código devuelto Descripción
S_OK
 El método se completó correctamente.
MK_S_MONIKERALREADYREGISTERED
 El par moniker/object se registró correctamente, pero ese otro objeto (posiblemente el mismo objeto) ya se ha registrado con el mismo moniker.

Comentarios

Este método registra un puntero a un objeto bajo un moniker que identifica el objeto. El moniker se usa como clave cuando se busca la tabla con IRunningObjectTable::GetObject.

Cuando se registra un objeto, rot siempre llama a AddRef en el objeto . Para un registro débil (ROTFLAGS_REGISTRATIONKEEPSALIVE no establecido), ROT liberará el objeto cada vez que se libere la última referencia fuerte al objeto. Para un registro seguro (ROTFLAGS_REGISTRATIONKEEPSALIVE establecido), el ROT impide que el objeto se destruya hasta que se revoque explícitamente el registro del objeto.

Un servidor registrado como LocalService o RunAs puede establecer la marca de ROTFLAGS_ALLOWANYCLIENT en su llamada a Register para permitir que cualquier cliente se conecte a él. Un servidor que establece este bit debe tener su nombre ejecutable en la sección AppID del Registro que hace referencia al AppID para el ejecutable. Un servidor "activar como activador" (no registrado como LocalService o RunAs) no debe establecer esta marca en su llamada a Register. Para obtener más información sobre la instalación de servicios, consulte Instalación como una aplicación de servicio.

Al registrar un segundo objeto con el mismo moniker o volver a registrar el mismo objeto con el mismo moniker, se crea una segunda entrada en el ROT. En este caso, Register devuelve MK_S_MONIKERALREADYREGISTERED. Cada llamada a Register debe coincidir con una llamada a IRunningObjectTable::Revoke porque incluso las entradas duplicadas tienen distintos identificadores pdwRegister . Un problema con los registros duplicados es que no hay ninguna manera de determinar qué objeto se devolverá si el moniker se especifica en una llamada posterior a IRunningObjectTable::IsRunning.

Notas a los autores de llamadas

Si es un proveedor de moniker (es decir, entrega monikers que identifican los objetos para que sean accesibles para otros), debe llamar al método Register para registrar los objetos cuando empiecen a ejecutarse. También debe llamar a este método si cambia el nombre de los objetos mientras se cargan.

El tipo de proveedor de moniker más común es un origen de vínculo de documento compuesto. Esto incluye aplicaciones de servidor que admiten la vinculación a sus documentos (o partes de un documento) y aplicaciones de contenedor que admiten la vinculación a incrustaciones dentro de sus documentos. Las aplicaciones de servidor que no admiten la vinculación también pueden usar rot para cooperar con aplicaciones contenedoras que admiten la vinculación a incrustaciones.

Si está escribiendo una aplicación de servidor, debe registrar un objeto con rot cuando empiece a ejecutarse, normalmente en la implementación de IOleObject::D oVerb. El objeto debe estar registrado en su moniker completo, lo que requiere obtener el moniker de su documento contenedor mediante IOleClientSite::GetMoniker. También debe revocar y volver a registrar el objeto en la implementación de IOleObject::SetMoniker, al que se llama si se cambia el nombre del documento contenedor.

Si va a escribir una aplicación contenedora que admita la vinculación a incrustaciones, debe registrar el documento con rot cuando se cargue. Si se cambia el nombre del documento, debe revocarlo y volver a registrarlo con ROT y llamar a IOleObject::SetMoniker para cualquier objeto incrustado del documento para darles la oportunidad de volver a registrarse.

Los objetos registrados en ROT deben revocarse explícitamente cuando el objeto ya no se está ejecutando o cuando cambia su moniker. Esta revocación es importante porque no hay forma de que el sistema quite automáticamente las entradas del ROT. Debe almacenar en caché el identificador escrito a través de pdwRegister y usarlo en una llamada a IRunningObjectTable::Revoke para revocar el registro. Para un registro seguro, se libera una referencia segura cuando se revoca el registro de objetos.

A partir de Windows Server 2003, si hay entradas obsoletas que permanecen en el ROT debido a problemas inesperados del servidor, COM quitará automáticamente estas entradas obsoletas del ROT.

La implementación del sistema de Register llama a IMoniker::Reduce en el parámetro pmkObjectName para asegurarse de que el moniker está totalmente reducido antes del registro. Si más de un moniker totalmente reducido conoce un objeto, debe registrarse en todos estos monikers.

Requisitos

Requisito Value
Cliente mínimo compatible Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado objidl.h

Consulte también

IRunningObjectTable