--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
+ <meta http-equiv="X-UA-Compatible" content="IE=9" />
+ <link rel="stylesheet" type="text/css" href="../../css/styles.css" />
+ <link rel="stylesheet" type="text/css" href="../../css/snippet.css" />
+ <script type="text/javascript" src="../../scripts/snippet.js"></script>
+ <script type="text/javascript" src="../../scripts/jquery.util.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../../scripts/common.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../../scripts/core.js" charset="utf-8"></script>
+ <script type="text/javascript" src="../../scripts/search.js" charset="utf-8"></script>
+ <title>Geofences</title>
+</head>
+<body onload="prettyPrint()" style="overflow: auto;">
+<div id="toc-navigation">
+ <div id="profile">
+ <p><img alt="Mobile C#" src="../../images/mobile_s_cs.png"/></p>
+ </div>
+
+ <div id="toc_border"><div id="toc">
+ <p class="toc-title">Dependencies</p>
+ <ul class="toc">
+ <li>Tizen 4.0 and Higher for Mobile</li>
+ </ul>
+ <p class="toc-title">Content</p>
+ <ul class="toc">
+ <li><a href="#manager">Geofence Service</a></li>
+ <li><a href="#definition">Geofence Definition</a></li>
+ <li><a href="#settings">Geofence Management through My Places</a></li>
+ <li><a href="#prerequisites">Prerequisites</a></li>
+ <li><a href="#start">Starting the Geofence Service</a></li>
+ <li><a href="#status">Monitoring Geofence State Changes</a></li>
+ <li><a href="#track">Tracking the User for Geofence Crossing Alerts</a></li>
+ <li><a href="#proximity">Tracking the User for Proximity Alerts</a></li>
+ <li><a href="#info">Retrieving Geofence Information</a></li>
+ </ul>
+ <p class="toc-title">Related Info</p>
+ <ul class="toc">
+ <li><a href="https://developer.tizen.org/dev-guide/csapi/namespaceTizen_1_1Location_1_1Geofence.html">Tizen.Location.Geofence Namespace</a></li>
+ </ul>
+ </div></div>
+</div>
+
+<div id="container"><div id="contents"><div class="content">
+<h1>Geofences</h1>
+<p>A geofence is a virtual perimeter for a real-world geographic area. A geofence is defined by either a geopoint and radius for geopoint geofences, or by a MAC address for Wi-Fi and Bluetooth geofences. The geofence feature alerts the user when the geofence state changes (the user crosses the perimeter).</p>
+
+<p>This feature is supported in mobile applications only.</p>
+
+<p>The main features of the Tizen.Location.Geofence namespace include:</p>
+<ul>
+<li>Using the geofence service
+<p>You can <a href="#manager">use the geofence service</a> to create different types of geofences and retrieve information about them, get the geofence event state, and track the user for alerts.</p></li>
+<li>Defining a geofence
+<p>You can <a href="#definition">define the type of the geofence</a> when creating one.</p></li>
+<li>Managing the geofence service
+<p>You can allow the user to <a href="#settings">manage the geofence places and fences</a> through My Places.</p></li>
+</ul>
+
+<p align="center"><strong>Figure: Geofence architecture</strong></p>
+<p align="center"><img alt="Geofence architecture" src="../../images/geofence.png" /></p>
+
+<h2 id="manager">Geofence Service</h2>
+
+<p>With the geofence service, you can:</p>
+<ul>
+ <li><a href="#start">Create different types of geofences</a></li>
+ <li><a href="#status">Get the current state</a></li>
+ <li>Get <a href="#track">in and out alerts</a> and <a href="#proximity">proximity alerts</a>
+ <p>You can get notifications when the user approaches or crosses any geofences they have defined.</p></li>
+ <li><a href="#info">Retrieve information about created geofences</a></li>
+</ul>
+<p>The device can receive alerts about the geofence when a particular geofence service is started using the <code>Start()</code> method of the <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Location_1_1Geofence_1_1GeofenceManager.html">Tizen.Location.Geofence.GeofenceManager</a> class.</p>
+
+<p>If the user revokes a permission to use the location information, an <code>UnauthorizedAccessException</code> is returned back to the application attempting to use the geofence service.</p>
+
+<p>Asynchronous geofence-related alerts (in or out) and event handling (a fence added or removed) are implemented with event handlers. Geofence alerts are received using the values of the <a href="https://developer.tizen.org/dev-guide/csapi/namespaceTizen_1_1Location_1_1Geofence.html#a0c8b8741b6e33113bc8eff5799f90458">Tizen.Location.Geofence.GeofenceState</a> enumeration.</p>
+
+<h2 id="definition">Geofence Definition</h2>
+<p>Geofence definition refers to defining an instance of the <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Location_1_1Geofence_1_1Fence.html">Tizen.Location.Geofence.Fence</a> class.</p>
+<p>The 3 types of available geofences are geopoint, Wi-Fi, and Bluetooth. When creating the geofence, define the type using the values of the <a href="https://developer.tizen.org/dev-guide/csapi/namespaceTizen_1_1Location_1_1Geofence.html#a4ce7bdedb0e432403aa64572ae6a98f6">Tizen.Location.Geofence.FenceType</a> enumeration.</p>
+<p>Creating a geopoint geofence requires a geopoint and a radius, whereas Wi-Fi and Bluetooth geofences require a MAC address. Based on the defined geofence type, the geofence manager creates the fence for the particular application.</p>
+
+<h2 id="settings">Geofence Management through My Places</h2>
+ <p>Tizen provides the user a way of managing geofence places and fences through the My places application. The following figure shows the default places and supported fence types.</p>
+ <p align="center"><strong>Figure: My places</strong></p>
+ <p align="center"><img alt="My places" src="../../images/geofence_setting.png" style="display: block; text-align: center; margin-left: auto; margin-right: auto" /></p>
+ <p>My places controls the adding, removing, and updating of places and fences. <strong>Home</strong>, <strong>Office</strong>, and <strong>Car</strong> are the default places, and <strong>Map</strong>, <strong>Wi-Fi</strong>, and <strong>Bluetooth</strong> are the supported fence methods. <strong>Car</strong> supports only Wi-Fi and Bluetooth as fence methods.</p>
+
+<h2 id="prerequisites">Prerequisites</h2>
+
+<p>To use the methods and properties of the <a href="https://developer.tizen.org/dev-guide/csapi/namespaceTizen_1_1Location_1_1Geofence.html">Tizen.Location.Geofence</a> namespace, include it in your application:</p>
+<pre class="prettyprint">
+using Tizen.Location.Geofence;
+</pre>
+
+<h2 id="start">Starting the Geofence Service</h2>
+
+<p>To start the geofence service:</p>
+<ol>
+
+<li>Create a <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Location_1_1Geofence_1_1GeofenceManager.html">Tizen.Location.Geofence.GeofenceManager</a> object:
+<pre class="prettyprint">
+GeofenceManager manager = new GeofenceManager();
+</pre>
+<p>Each geofence manager is an independent service. The event handlers are set for a given geofence manager and are called only if the service is started by their manager.</p></li>
+
+<li><p>Create a place to be used for the geofences:</p>
+<pre class="prettyprint">
+VirtualPerimeter perimeter = new VirtualPerimeter(manager);
+int placeId = perimeter.AddPlaceName("Place");
+</pre>
+<div class="note">
+ <strong>Note</strong>
+ A place is used to accommodate a number of geofences and is identified by a place ID. Each place can have a name. A geofence is identified by a geofence ID.
+</div>
+</li>
+
+<li>Create the geofences you need:
+<ul>
+<li>Geopoint geofence:
+<pre class="prettyprint">
+double latitude = 12.756738;
+double longitude = 77.386474;
+int radius = 100;
+char* address = "India";
+Fence fence = Fence.CreateGPSFence(placeId, latitude, longitude, radius, address);
+</pre>
+</li>
+<li>Bluetooth geofence:
+<pre class="prettyprint">
+char* bssid = "82:45:67:7E:4A:3B";
+char* ssid = "Cafeteria";
+Fence fence = Fence.CreateBTFence(place_id, bssid, ssid);
+</pre>
+</li>
+</ul></li>
+<li><p>Add the geofence to the geofence manager:</p>
+<pre class="prettyprint">
+int geofenceId = perimeter.AddGeofence(fence);
+</pre></li>
+
+<li>Start the geofence service using the <code>Start()</code> method of the <code>Tizen.Location.Geofence.GeofenceManager</code> class.
+<p>This call is asynchronous and only initiates the process of starting the service. Once the service is started, the added event handlers are invoked when their corresponding events take place. To know when the service becomes enabled, use the <code>StateChanged</code> event of the <code>Tizen.Location.Geofence.GeofenceManager</code> class.</p>
+<pre class="prettyprint">
+manager.Start(geofenceId);
+</pre></li>
+
+<li>Using the geofence service for geopoints adds to power consumption, so if the service is not used, stop the status alerts using the <code>Stop()</code> method of the <code>Tizen.Location.Geofence.GeofenceManager</code> class. Call the <code>Start()</code> method again if the alerts are needed.
+<pre class="prettyprint">
+manager.Stop(geofenceId);
+</pre></li>
+
+<li><p>Destroy all used resources using the <code>Dispose()</code> method of the <code>Tizen.Location.Geofence.GeofenceManager</code> class:</p>
+<pre class="prettyprint">
+manager.Dispose();
+manager = NULL;
+</pre>
+<p>If you destroy the <code>Tizen.Location.Geofence.GeofenceManager</code> instance, there is no need to call the <code>Stop()</code> method to stop the service, as the service is automatically stopped.</p></li></ol>
+
+<h2 id="status">Monitoring Geofence State Changes</h2>
+
+<p>To track the state of the geofence, use the <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Location_1_1Geofence_1_1GeofenceManager.html#a77795e3a389230849d7f58fa3df5cccd">Tizen.Location.Geofence.GeofenceManager.GeoFenceEventChanged</a> event. An event handler is invoked whenever there is a request from the user, such as to add a geofence or to start a geofence service.</p>
+
+<ol>
+<li>Add the event handler using the <code>GeofenceEventChanged</code> event of the <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Location_1_1Geofence_1_1GeofenceManager.html">Tizen.Location.Geofence.GeofenceManager</a> class:
+<pre class="prettyprint">
+manager.GeofenceEventChanged += handler;
+</pre>
+</li>
+<li>Get the success or failure state of the event in the handler:
+<pre class="prettyprint">
+EventHandler<GeofenceResponseEventArgs> handler = (object sender, GeofenceResponseEventArgs args) =>
+{
+ placeId = args.PlaceId;
+ FenceId = args.FenceId;
+ errorCode = args.ErrorCode;
+ eventType = args.EventType;
+};
+</pre>
+
+<div class="note">
+<strong>Note</strong>
+The geofence change event handler is used to let the user know whether the request is successful on the server side. This handler is invoked only in the case of an asynchronous method. For a synchronous method, an error is immediately returned.
+</div>
+</li></ol>
+
+<h2 id="track">Tracking the User for Geofence Crossing Alerts</h2>
+
+<p>To get information about whether the user has crossed the boundary of the geofence:</p>
+<ul>
+<li>Receive event-based notifications with an event handler.
+<p>You can be notified when the user crosses a particular fence. The handler receives the current state of the user (whether the user is in or out of the virtual boundaries of a geofence) with each call.</p>
+<ol>
+ <li>Define the event handler:
+<pre class="prettyprint">
+EventHandler<GeofenceStateEventArgs> handler = (object sender, GeofenceStateEventArgs args) => {};
+</pre>
+</li>
+ <li>Register the handler using the <code>StateChanged</code> event of the <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Location_1_1Geofence_1_1GeofenceManager.html">Tizen.Location.Geofence.GeofenceManager</a> class.
+<pre class="prettyprint">
+manager.StateChanged += handler;
+</pre></li>
+</ol>
+</li>
+<li>Retrieve the current state on request.
+ <p>You can get the current state of the user with respect to a geofence, such as their in or out state and the duration of the current state.</p>
+<ol><li><p>Create a <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Location_1_1Geofence_1_1FenceStatus.html">Tizen.Location.Geofence.FenceStatus</a> instance:</p>
+<pre class="prettyprint">
+FenceStatus status = new FenceStatus(fenceId);
+</pre></li>
+<li>To get the current state and duration of that state, use the <code>State</code> and <code>Duration</code> properties of the <code>Tizen.Location.Geofence.FenceStatus</code> class:
+<pre class="prettyprint">
+GeofenceState state = status.State;
+int duration = status.Duration;
+</pre>
+<p>The duration is provided in seconds.</p></li>
+<li>When no longer needed, destroy the <code>Tizen.Location.Geofence.FenceStatus</code> instance with the <code>Dispose()</code> method:
+<pre class="prettyprint">
+status.Dispose();
+</pre>
+</li></ol></li>
+</ul>
+
+<h2 id="proximity">Tracking the User for Proximity Alerts</h2>
+
+<p>To get information about the user's proximity to a geofence, use an event handler that receives the user's proximity with each call:</p>
+<ol>
+<li>Define the event handler:
+<pre class="prettyprint">
+EventHandler<ProximityStateEventArgs> handler = (object sender, ProximityStateEventArgs args) => {};
+</pre></li>
+<li>
+Register the handler using the <code>ProximityChanged</code> event of the <a href="https://developer.tizen.org/dev-guide/csapi/classTizen_1_1Location_1_1Geofence_1_1GeofenceManager.html">Tizen.Location.Geofence.GeofenceManager</a> class.
+<pre class="prettyprint">
+manager.ProximityChanged += handler;
+</pre>
+</li></ol>
+
+<h2 id="info">Retrieving Geofence Information</h2>
+
+<p>To get information about a geofence:</p>
+<ul><li><p>Get common information (such as the type and place) about any type of geofence:</p>
+<pre class="prettyprint">
+int placeId = fence.PlaceId;
+Fence type = fence.Type;
+</pre></li>
+<li><p>Get information specific to a geopoint geofence:</p>
+<pre class="prettyprint">
+double latitude = fence.Latitude;
+double longitude = fence.Longitude;
+int radius = fence.Radius;
+string address = fence.Address;
+</pre></li>
+<li>Get information specific to a Wi-Fi or Bluetooth geofence:
+<pre class="prettyprint">
+string bssid = fence.Bssid;
+string ssid = fence.Ssid;
+</pre></li></ul>
+
+<script type="text/javascript" src="../../scripts/jquery.zclip.min.js"></script>
+<script type="text/javascript" src="../../scripts/showhide.js"></script>
+</div></div></div>
+
+<a class="top sms" href="#"><img src="../../images/btn_top.gif" alt="Go to top" /></a>
+<div id="footer">
+<p class="footer">Except as noted, this content - excluding the Code Examples - is licensed under <a href="http://creativecommons.org/licenses/by/3.0/legalcode" target="_blank">Creative Commons Attribution 3.0</a> and all of the Code Examples contained herein are licensed under <a href="https://www.tizen.org/bsd-3-clause-license" target="_blank">BSD-3-Clause</a>.<br/>For details, see the <a href="https://www.tizen.org/content-license" target="_blank">Content License</a>.</p>
+</div>
+</body>
+</html>
projects / sdk / online-doc.git / commitdiff
