Método ILocation::RequestPermissions (locationapi.h)

[A API de Localização do Win32 está disponível para uso nos sistemas operacionais especificados na seção Requisitos. Ele poderá ser alterado ou ficar indisponível em versões subsequentes. Em vez disso, use a API Windows.Devices.Geolocation . ]

Abre uma caixa de diálogo do sistema para solicitar permissão do usuário para habilitar dispositivos de localização.

Sintaxe

HRESULT RequestPermissions(
  [in] HWND  hParent,
  [in] IID   *pReportTypes,
  [in] ULONG count,
       BOOL  fModal
);

Parâmetros

[in] hParent

HWND para a janela pai. Esse parâmetro é opcional. No Windows 8, a caixa de diálogo sempre será modal se hParent for fornecido e não modal se hParent for NULL.

[in] pReportTypes

Ponteiro para uma matriz IID . Essa matriz deve conter IDs de interface para todos os tipos de relatório para os quais você está solicitando permissão. As IDs de interface dos tipos de relatório válidos são IID_ILatLongReport e IID_ICivicAddressReport. A contagem de IDs deve corresponder ao valor especificado por meio do parâmetro count .

[in] count

A contagem de IDs de interface contidas em pReportTypes.

fModal

Este parâmetro não é usado.

Valor retornado

Esse método pode retornar um desses valores.

A tabela a seguir descreve códigos de retorno quando a chamada é síncrona.

Código de retorno	Descrição
S_OK	Os serviços de localização habilitados pelo usuário. O método foi bem-sucedido.
HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED)	A plataforma de localização está desabilitada. Um administrador desativou a plataforma de localização.
HRESULT_FROM_WIN32(ERROR_CANCELLED)	O usuário não habilitou o acesso aos serviços de localização nem cancelou a caixa de diálogo.

 

A tabela a seguir descreve códigos de retorno quando a chamada é assíncrona.

Código de retorno	Descrição
S_OK	O usuário habilitou o acesso aos serviços de localização. O método foi bem-sucedido.
E_INVALIDARG	Um argumento não é válido.
HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED)	A plataforma de localização está desabilitada. Um administrador desativou a plataforma de localização. A caixa de diálogo não foi mostrada.

Comentários

Se o usuário optar por não habilitar os serviços de localização, o Windows não mostrará a caixa de diálogo de permissões novamente.

Nota Chamadas assíncronas repetidas para RequestPermissions exibirão várias instâncias da caixa de diálogo Habilitar serviços de localização e podem potencialmente inundar a tela com caixas de diálogo, resultando em uma experiência ruim do usuário. Se você acha que outros sensores de localização podem ser instalados após sua primeira chamada para RequestPermissions, exigindo outra chamada para RequestPermissions, você deve chamar RequestPermissions de forma síncrona ou aguardar até que todos os sensores de localização sejam instalados para fazer uma chamada assíncrona.

 

Nota Fazer uma chamada síncrona do thread da interface do usuário de um aplicativo do Windows pode bloquear o thread da interface do usuário e tornar o aplicativo menos responsivo. Para evitar isso, não faça uma chamada síncrona para RequestPermissions do thread da interface do usuário.

 

Nota Se um aplicativo em execução no modo protegido, como um Objeto Auxiliar do Navegador (BHO) para Internet Explorer, chamar RequestPermissions e o usuário optar por não habilitar o local usando a caixa de diálogo, o provedor de localização não será habilitado, mas o Windows exibirá a caixa de diálogo novamente se RequestPermissions for chamado novamente pelo mesmo usuário.

 

Exemplos

O exemplo a seguir demonstra como chamar RequestPermissions para solicitar permissão para relatórios de latitude/longitude.

             // Array of report types of interest. Other ones include IID_ICivicAddressReport
            IID REPORT_TYPES[] = { IID_ILatLongReport };

            // Request permissions for this user account to receive location data for all the
            // types defined in REPORT_TYPES (which is currently just one report type)
            // The last parameter is not used.
            if (FAILED(spLocation->RequestPermissions(
                  NULL, 
                  REPORT_TYPES, 
                  ARRAYSIZE(REPORT_TYPES), 
                  TRUE))) 
            {
                wprintf(L"Warning: Unable to request permissions.\n");
            }

Requisitos

Cliente mínimo com suporte	Windows 7 [somente aplicativos da área de trabalho], Windows 7
Servidor mínimo com suporte	Nenhum compatível
Plataforma de Destino	Windows
Cabeçalho	locationapi.h
DLL	LocationAPI.dll