Método IUPnPRegistrar::RegisterRunningDevice (upnphost.h)
O método RegisterRunningDevice registra um dispositivo em execução com o host do dispositivo. As informações do dispositivo são armazenadas pelo host do dispositivo. Em seguida, o host do dispositivo retorna um identificador de dispositivo e publica e anuncia o dispositivo na rede. A publicação deste dispositivo não persiste entre as inicializações do sistema.
Sintaxe
HRESULT RegisterRunningDevice(
[in] BSTR bstrXMLDesc,
[in] IUnknown *punkDeviceControl,
[in] BSTR bstrInitString,
[in] BSTR bstrResourcePath,
[in] long nLifeTime,
[out] BSTR *pbstrDeviceIdentifier
);
Parâmetros
[in] bstrXMLDesc
Especifica o modelo de descrição do dispositivo XML do dispositivo a ser registrado.
[in] punkDeviceControl
Especifica o ponteiro IUnknown para o objeto de controle de dispositivo do dispositivo.
[in] bstrInitString
Identifica a cadeia de caracteres de inicialização específica para o dispositivo. Essa cadeia de caracteres é passada posteriormente para IUPnPDeviceControl::Initialize.
[in] bstrResourcePath
Especifica o local do diretório de recursos do dispositivo. Esse diretório de recursos contém os arquivos de ícone e descrições de serviço especificados no modelo de descrição do dispositivo bstrXMLDesc.
[in] nLifeTime
Especifica o tempo de vida do anúncio do dispositivo, em segundos. Depois que o tempo limite expirar, os comunicados serão atualizados. Se você especificar zero, o valor padrão de 1800 (30 minutos) será usado. O valor mínimo permitido é 900 (15 minutos); se você especificar algo menor que 900, um erro será retornado.
[out] pbstrDeviceIdentifier
Recebe o identificador do dispositivo. Use esse identificador ao cancelar o registro ou registrar novamente o dispositivo. Salve esta ID do dispositivo; você deve usá-lo ao chamar UnregisterDevice.
Retornar valor
Se o método for bem-sucedido, o valor retornado será S_OK. Caso contrário, o método retornará um dos códigos de erro COM definidos em WinError.h ou um dos seguintes códigos de erro específicos do UPnP.
| Código de retorno | Descrição |
|---|---|
|
Existe um elemento duplicado. |
|
Existe uma ID de serviço duplicada para um serviço no mesmo dispositivo pai. |
|
A descrição do dispositivo não é válida. |
|
Um erro está presente no elemento de ícone da descrição do dispositivo. |
|
Um erro está presente em um elemento de serviço na descrição do dispositivo. |
|
Um elemento necessário está ausente. |
Comentários
O cliente que invoca esse método deve ser capaz de representar LocalService para concluir o processamento desse método.
O método IUPnPDeviceControl::Initialize é invocado quando a primeira solicitação de controle ou evento é recebida.
Use o identificador retornado em pbstrDeviceIdentifier ao invocar UnregisterDevice ou IUPnPReregistrar::ReregisterRunningDevice.
O registro deste dispositivo não persiste entre as inicializações do sistema.
Os erros comuns que podem ocorrer ao invocar essa função incluem:
- O objeto COM necessário não foi encontrado.
- Não há acesso ao objeto COM para LocalService.
- Interfaces COM subordinadas.
- Os limites de descrição XML (consulte Criando uma descrição do dispositivo).
- As variáveis evented não retornaram códigos de êxito e o dispositivo foi desligado.
- A descrição do serviço era inválida. Use validatesd.exe para garantir que as descrições de serviço sejam válidas.
- O serviço não implementou IUPnPEventSource e não retornou um código de êxito para IUPnPEventSource::Advise e o dispositivo foi desligado.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Nenhum compatível |
| Plataforma de Destino | Windows |
| Cabeçalho | upnphost.h |
| DLL | Upnphost.dll |