ILocation::RegisterForReport method (locationapi.h)

[API Lokasi Win32 tersedia untuk digunakan dalam sistem operasi yang ditentukan di bagian Persyaratan. Ini dapat diubah atau tidak tersedia dalam versi berikutnya. Sebagai gantinya, gunakan WINDOWS.Devices.Geolocation API. ]

Meminta peristiwa laporan lokasi.

Sintaks

HRESULT RegisterForReport(
  [in] ILocationEvents *pEvents,
  [in] REFIID          reportType,
  [in] DWORD           dwRequestedReportInterval
);

Parameter

[in] pEvents

Arahkan ke antarmuka panggilan balik ILocationEvents tempat pemberitahuan peristiwa yang diminta akan diterima.

[in] reportType

GUID yang menentukan ID antarmuka jenis laporan untuk menerima pemberitahuan peristiwa.

[in] dwRequestedReportInterval

DWORD yang menentukan waktu berlalu yang diminta, dalam milidetik, antara pemberitahuan peristiwa untuk jenis laporan yang ditentukan. Jika dwRequestedReportInterval adalah nol, tidak ada interval minimum yang ditentukan dan aplikasi Anda meminta untuk menerima peristiwa pada interval default sensor lokasi. Lihat Keterangan.

Nilai kembali

Metode mengembalikan HRESULT. Nilai yang mungkin termasuk, tetapi tidak terbatas pada, yang ada dalam tabel berikut.

Menampilkan kode	Deskripsi
S_OK	Metode berhasil.
HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED)	reportType selain IID_ILatLongReport atau IID_ICivicAddressReport.
HRESULT_FROM_WIN32(ERROR_ALREADY_REGISTERED)	reportType sudah terdaftar.

Keterangan

Interval yang Anda minta dengan menggunakan parameter dwRequestedReportInterval mewakili jumlah waktu terpendek antar peristiwa. Ini berarti Bahwa Anda meminta untuk menerima pemberitahuan peristiwa tidak lebih sering dari yang ditentukan, tetapi waktu yang berlalu mungkin jauh lebih lama. Gunakan parameter dwRequestedReportInterval untuk membantu memastikan bahwa pemberitahuan peristiwa tidak menggunakan lebih banyak sumber daya prosesor daripada yang diperlukan.

Penyedia lokasi tidak diperlukan untuk memberikan laporan pada interval yang Anda minta. Panggil GetReportInterval untuk menemukan pengaturan interval laporan yang sebenarnya.

Aplikasi yang perlu mendapatkan data lokasi hanya sekali, untuk mengisi formulir atau menempatkan lokasi pengguna di peta, harus mendaftar untuk peristiwa dan menunggu peristiwa laporan pertama seperti yang dijelaskan dalam Menunggu Laporan Lokasi.

Contoh

Contoh berikut memanggil RegisterForReport untuk berlangganan peristiwa.

#include <windows.h>
#include <atlbase.h>
#include <atlcom.h>
#include <LocationApi.h> // This is the main Location API header
#include "LocationCallback.h" // This is our callback interface that receives Location reports.

class CInitializeATL : public CAtlExeModuleT<CInitializeATL>{};
CInitializeATL g_InitializeATL; // Initializes ATL for this application. This also does CoInitialize for us

int wmain()
{
    HRESULT hr = CoInitializeEx(NULL, COINIT_MULTITHREADED | COINIT_DISABLE_OLE1DDE);;
    if (SUCCEEDED(hr))
    {
        CComPtr<ILocation> spLocation; // This is the main Location interface
        CComObject<CLocationEvents>* pLocationEvents = NULL; // This is our callback object for location reports
        IID REPORT_TYPES[] = { IID_ILatLongReport }; // Array of report types of interest. Other ones include IID_ICivicAddressReport

        hr = spLocation.CoCreateInstance(CLSID_Location); // Create the Location object

        if (SUCCEEDED(hr))
        {
            hr = CComObject<CLocationEvents>::CreateInstance(&pLocationEvents); // Create the callback object
            if (NULL != pLocationEvents)
            {
                pLocationEvents->AddRef();
            }
        }

        if (SUCCEEDED(hr))
        {
            // Request permissions for this user account to receive location data for all the
            // types defined in REPORT_TYPES (which is currently just one report)
            if (FAILED(spLocation->RequestPermissions(NULL, REPORT_TYPES, ARRAYSIZE(REPORT_TYPES), FALSE))) // FALSE means an asynchronous request
            {
                wprintf(L"Warning: Unable to request permissions.\n");
            }

            // Tell the Location API that we want to register for reports (which is currently just one report)
            for (DWORD index = 0; index < ARRAYSIZE(REPORT_TYPES); index++)
            {
                hr = spLocation->RegisterForReport(pLocationEvents, REPORT_TYPES[index], 0);
            }
        }

        if (SUCCEEDED(hr))
        {
            // Wait until user presses a key to exit app. During this time the Location API
            // will send reports to our callback interface on another thread.
            system("pause");

            // Unregister from reports from the Location API
            for (DWORD index = 0; index < ARRAYSIZE(REPORT_TYPES); index++)
            {
                spLocation->UnregisterForReport(REPORT_TYPES[index]);
            }
        }

        // Cleanup
        if (NULL != pLocationEvents)
        {
            pLocationEvents->Release();
            pLocationEvents = NULL;
        }

        CoUninitialize();
    }

    return 0;
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 7 [hanya aplikasi desktop],Windows 7
Server minimum yang didukung	Tidak ada yang didukung
Target Platform	Windows
Header	locationapi.h
DLL	LocationAPI.dll

Lihat juga

ILocation

ILocationEvents