Método IUPnPRegistrar::RegisterDevice (upnphost.h)
O método RegisterDevice registra um dispositivo 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.
Sintaxe
HRESULT RegisterDevice(
[in] BSTR bstrXMLDesc,
[in] BSTR bstrProgIDDeviceControlClass,
[in] BSTR bstrInitString,
[in] BSTR bstrContainerId,
[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] bstrProgIDDeviceControlClass
Especifica o ProgID de um objeto de controle de dispositivo que implementa a interface IUPnPDeviceControl . Essa interface deve ser um servidor COM em processo (CLSCTX_INPROC_SERVER) e deve estar acessível ao LocalService.
[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] bstrContainerId
Especifica uma cadeia de caracteres que identifica o grupo de processos ao qual o dispositivo pertence. Todos os dispositivos com a mesma ID de contêiner estão contidos no mesmo processo.
[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. O diretório de recursos também pode conter os arquivos de apresentação. No entanto, isso é opcional.
[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 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
Um dispositivo é instanciado e IUPnPDeviceControl::Initialize é invocado quando uma solicitação de controle ou evento é recebida.
Use o identificador retornado em pbstrDeviceIdentifier ao invocar UnregisterDevice ou IUPnPReregistrar::ReregisterDevice.
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 |