Google Git
Sign in
apache / mynewt-site / refs/heads/asf-site / . / v1_1_0 / os / tutorials / bleprph / bleprph-gap-event / index.html
blob: 27797dc03358191f5850c90e88e7ca433b2c2ab4 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- This is broken by doc revisioning.
-->
<link rel="shortcut icon" href="../../../../img/favicon.ico">
<title>GAP Event Callbacks - Apache Mynewt</title>
<link href="../../../../css/bootstrap-3.0.3.min.css" rel="stylesheet">
<link rel="stylesheet" href="../../../../css/highlight.css">
<link href="../../../../css/base.css" rel="stylesheet">
<link href="../../../../css/custom.css" rel="stylesheet">
<link href="../../../../css/v2.css" rel="stylesheet">
<link href="https://fonts.googleapis.com/css?family=Lato" rel="stylesheet">
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css">
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
<![endif]-->
<script>
(function(i, s, o, g, r, a, m) {
i["GoogleAnalyticsObject"] = r;
(i[r] =
i[r] ||
function() {
(i[r].q = i[r].q || []).push(arguments);
}),
(i[r].l = 1 * new Date());
(a = s.createElement(o)), (m = s.getElementsByTagName(o)[0]);
a.async = 1;
a.src = g;
m.parentNode.insertBefore(a, m);
})(window, document, "script", "//www.google-analytics.com/analytics.js", "ga");
ga("create", "UA-72162311-1", "auto");
ga("send", "pageview");
</script>
</head>
<body class="GAP Event Callbacks">
<div class="container">
<div class="row v2-main-banner">
<a class="logo-cell" href="/">
<img class="logo" src="/img/logo.png">
</a>
<div class="tagline-cell">
<h4 class="tagline">An OS to build, deploy and securely manage billions of devices</h4>
</div>
<div class="news-cell">
<div class="well">
<h4>Latest News:</h4> <a href="/download">Apache Mynewt 1.12.0, Apache NimBLE 1.7.0 </a> released (April 4, 2024)
</div>
</div>
</div>
</div>
<nav id="navbar" class="navbar navbar-inverse affix-top" data-spy="affix" data-offset-top="150" role="navigation">
<div class="container">
<!-- Collapsed navigation -->
<div class="navbar-header">
<!-- Expander button -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<!-- Expanded navigation -->
<div class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav navbar-right">
<li
class=""
>
<a href="/"><i class="fa fa-home" style="font-size: larger;"></i></a>
</li>
<li
class="important"
>
<a href="/quick-start/">Quick Start</a>
</li>
<li
class=""
>
<a href="/about/">About</a>
</li>
<li
class=""
>
<a href="/talks/">Talks</a>
</li>
<li
class="active"
>
<a href="/documentation/">Documentation</a>
</li>
<li
class=""
>
<a href="/download/">Download</a>
</li>
<li
class=""
>
<a href="/community/">Community</a>
</li>
<li
class=""
>
<a href="/events/">Events</a>
</li>
</ul>
</div>
</div>
</nav>
<div class="container">
<div class="row">
<div class="col-md-3 v2-sidebar sidebar-container"><div id="docSidebar" class="hidden-print" role="complementary">
<div class="top">
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../../../search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search documentation" />
</div>
</form>
</div>
</div>
<ul class="toc-nav">
<li class="doc-version"><select class="form-control" onchange="if (this.value) window.location.href=this.value">
<option value="/latest">
Version: master
</option>
<option value="/v1_12_0/" >
Version: 1.12.0
</option>
<option value="/v1_11_0/" >
Version: 1.11.0
</option>
<option value="/v1_10_0/" >
Version: 1.10.0
</option>
<option value="/v1_9_0/" >
Version: 1.9.0
</option>
<option value="/v1_8_0/" >
Version: 1.8.0
</option>
<option value="/v1_7_0/" >
Version: 1.7.0
</option>
<option value="/v1_6_0/" >
Version: 1.6.0
</option>
<option value="/v1_5_0/" >
Version: 1.5.0
</option>
<option value="/v1_4_0/" >
Version: 1.4.0
</option>
<option value="/v1_3_0/os/introduction" >
Version: 1.3.0
</option>
<option value="/v1_2_0/os/introduction" >
Version: 1.2.0
</option>
<option value="/v1_1_0/os/introduction" selected="selected" >
Version: 1.1.0
</option>
<option value="/v1_0_0/os/introduction" >
Version: 1.0.0
</option>
<option value="/v0_9_0/os/introduction" >
Version: 0.9.0
</option>
</select></li>
<li ><a href="../../../introduction/">Mynewt Documentation</a>
<ul>
<li ><a href="../../../get_started/get_started/">Basic Setup</a>
</li>
<li >
<a href="../../../get_started/vocabulary/">Concepts</a>
</li>
<li ><a href="../../tutorials/">Tutorials</a>
<ul>
<li ><a href="../../blinky/">Project Blinky</a>
</li>
<li ><a href="../../repo/add_repos/">Work with repositories</a>
</li>
<li ><a href="../../project-slinky/">Project Slinky for Remote Comms</a>
</li>
<li><a href="
../../ble_bare_bones/
">Bluetooth Low Energy</a>
<ul>
<li >
<a href="../../ble_bare_bones/">BLE Bare Bones Application</a>
</li>
<li >
<a href="../../ibeacon/">BLE iBeacon</a>
</li>
<li >
<a href="../../eddystone/">BLE Eddystone</a>
</li>
<li ><a href="../bleprph-intro/">BLE Peripheral Project</a>
<ul>
<li >
<a href="../bleprph-svc-reg/">Service Registration</a>
</li>
<li >
<a href="../bleprph-chr-access/">Characteristic Access</a>
</li>
<li >
<a href="../bleprph-adv/">Advertising</a>
</li>
<li class="active">
<a href="./">GAP Event Callbacks</a>
</li>
<li >
<a href="../bleprph-app/">BLE Peripheral App</a>
</li>
</ul>
</li>
<li >
<a href="../../blehci_project/">BLE HCI interface</a>
</li>
</ul>
</li>
<li><a href="
../../event_queue/
">OS Fundamentals</a>
</li>
<li><a href="
../../add_newtmgr/
">Remote Device Management</a>
</li>
<li><a href="
../../sensors/sensors/
">Sensors</a>
</li>
<li><a href="
../../segger_rtt/
">Tooling</a>
</li>
<li><a href="
../../codesize/
">Other</a>
</li>
</ul>
</li>
<li ><a href="../../../os_user_guide/">OS User Guide</a>
</li>
<li><a href="
../../../../network/ble/ble_intro/
">BLE User Guide</a>
</li>
<li ><a href="../../../../newt/newt_intro/">Newt Tool Guide</a>
</li>
<li ><a href="../../../../newtmgr/overview/">Newt Manager Guide</a>
</li>
<li >
<a href="../../../../known_issues/">Known Issues</a>
</li>
</ul>
</li>
<li><a href="
../../../../faq/go_env/
">Appendix</a>
</li>
</ul>
</div></div>
<div class="col-md-9" role="main">
<div class="doc-header">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="/documentation/">Docs</a></li>
<li>&raquo; <a href="os/tutorials/bleprph/bleprph-intro/">BLE Peripheral Project</a></li>
<li>&raquo; <a href="os/tutorials/ble_bare_bones/">Bluetooth Low Energy</a></li>
<li>&raquo; <a href="os/tutorials/tutorials/">Tutorials</a></li>
<li>&raquo; <a href="os/introduction/">Mynewt Documentation</a></li>
<li>&raquo; GAP Event Callbacks</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/apache/mynewt-site/blob/master/docs/os/tutorials/bleprph/bleprph-gap-event.md"
class="icon icon-github"> Edit on GitHub</a>
</li>
</ul>
</div>
</div>
<div class="alert alert-warning">
<p>
Version 1.1.0 is not the most recent version of the Apache Mynewt
documentation. Click <a href="/latest">here</a> to read the latest
version.
</p>
</div>
<h2 id="ble-peripheral-project">BLE Peripheral Project</h2>
<h3 id="gap-event-callbacks">GAP Event callbacks</h3>
<p><br></p>
<h4 id="overview">Overview</h4>
<p>Every BLE connection has a <em>GAP event callback</em> associated with it. A
GAP event callback is a bit of application code which NimBLE uses to inform
you of connection-related events. For example, if a connection is terminated,
NimBLE lets you know about it with a call to that connection's callback.</p>
<p>In the <a href="bleprph-adv/">advertising section</a> of this tutorial, we saw how the
application specifies a GAP event callback when it begins advertising. NimBLE
uses this callback to notify the application that a central has connected to
your peripheral after receiving an advertisement. Let's revisit how <em>bleprph</em> specifies its connection callback when advertising:</p>
<p><br></p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code> <span style="color: #177500">/* Begin advertising. */</span>
<span style="color: #000000">memset</span>(<span style="color: #000000">&amp;adv_params</span>, <span style="color: #1C01CE">0</span>, <span style="color: #A90D91">sizeof</span> <span style="color: #000000">adv_params</span>);
<span style="color: #000000">adv_params</span>.<span style="color: #000000">conn_mode</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_GAP_CONN_MODE_UND</span>;
<span style="color: #000000">adv_params</span>.<span style="color: #000000">disc_mode</span> <span style="color: #000000">=</span> <span style="color: #000000">BLE_GAP_DISC_MODE_GEN</span>;
<span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_gap_adv_start</span>(<span style="color: #000000">BLE_ADDR_TYPE_PUBLIC</span>, <span style="color: #1C01CE">0</span>, <span style="color: #A90D91">NULL</span>, <span style="color: #000000">BLE_HS_FOREVER</span>,
<span style="color: #000000">&amp;adv_params</span>, <span style="color: #000000">bleprph_gap_event</span>, <span style="color: #A90D91">NULL</span>);
<span style="color: #A90D91">if</span> (<span style="color: #000000">rc</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>) {
<span style="color: #000000">BLEPRPH_LOG</span>(<span style="color: #000000">ERROR</span>, <span style="color: #C41A16">&quot;error enabling advertisement; rc=%d\n&quot;</span>, <span style="color: #000000">rc</span>);
<span style="color: #A90D91">return</span>;
}
</code></pre></div>
<p><br></p>
<h4 id="bleprph_gap_event">bleprph_gap_event()</h4>
<p>The <code>bleprph_gap_event()</code> function is <em>bleprph</em>'s GAP event callback; NimBLE
calls this function when the advertising operation leads to connection
establishment. Upon connection establishment, this callback becomes
permanently associated with the connection; all subsequent events related to
this connection are communicated through this callback.</p>
<p>Now let's look at the function that <em>bleprph</em> uses for all its connection
callbacks: <code>bleprph_gap_event()</code>.</p>
<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%;"><span></span><code><span style="color: #177500">/**</span>
<span style="color: #177500"> * The nimble host executes this callback when a GAP event occurs. The</span>
<span style="color: #177500"> * application associates a GAP event callback with each connection that forms.</span>
<span style="color: #177500"> * bleprph uses the same callback for all connections.</span>
<span style="color: #177500"> *</span>
<span style="color: #177500"> * @param event The type of event being signalled.</span>
<span style="color: #177500"> * @param ctxt Various information pertaining to the event.</span>
<span style="color: #177500"> * @param arg Application-specified argument; unuesd by</span>
<span style="color: #177500"> * bleprph.</span>
<span style="color: #177500"> *</span>
<span style="color: #177500"> * @return 0 if the application successfully handled the</span>
<span style="color: #177500"> * event; nonzero on failure. The semantics</span>
<span style="color: #177500"> * of the return code is specific to the</span>
<span style="color: #177500"> * particular GAP event being signalled.</span>
<span style="color: #177500"> */</span>
<span style="color: #A90D91">static</span> <span style="color: #A90D91">int</span>
<span style="color: #000000">bleprph_gap_event</span>(<span style="color: #A90D91">struct</span> <span style="color: #3F6E75">ble_gap_event</span> <span style="color: #000000">*event</span>, <span style="color: #A90D91">void</span> <span style="color: #000000">*arg</span>)
{
<span style="color: #A90D91">struct</span> <span style="color: #3F6E75">ble_gap_conn_desc</span> <span style="color: #000000">desc</span>;
<span style="color: #A90D91">int</span> <span style="color: #000000">rc</span>;
<span style="color: #A90D91">switch</span> (<span style="color: #000000">event-&gt;type</span>) {
<span style="color: #A90D91">case</span> <span style="color: #000000">BLE_GAP_EVENT_CONNECT</span>:
<span style="color: #177500">/* A new connection was established or a connection attempt failed. */</span>
<span style="color: #000000">BLEPRPH_LOG</span>(<span style="color: #000000">INFO</span>, <span style="color: #C41A16">&quot;connection %s; status=%d &quot;</span>,
<span style="color: #000000">event-&gt;connect</span>.<span style="color: #000000">status</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span> <span style="color: #000000">?</span> <span style="color: #C41A16">&quot;established&quot;</span> <span style="color: #000000">:</span> <span style="color: #C41A16">&quot;failed&quot;</span>,
<span style="color: #000000">event-&gt;connect</span>.<span style="color: #000000">status</span>);
<span style="color: #A90D91">if</span> (<span style="color: #000000">event-&gt;connect</span>.<span style="color: #000000">status</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>) {
<span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_gap_conn_find</span>(<span style="color: #000000">event-&gt;connect</span>.<span style="color: #000000">conn_handle</span>, <span style="color: #000000">&amp;desc</span>);
<span style="color: #000000">assert</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
<span style="color: #000000">bleprph_print_conn_desc</span>(<span style="color: #000000">&amp;desc</span>);
}
<span style="color: #000000">BLEPRPH_LOG</span>(<span style="color: #000000">INFO</span>, <span style="color: #C41A16">&quot;\n&quot;</span>);
<span style="color: #A90D91">if</span> (<span style="color: #000000">event-&gt;connect</span>.<span style="color: #000000">status</span> <span style="color: #000000">!=</span> <span style="color: #1C01CE">0</span>) {
<span style="color: #177500">/* Connection failed; resume advertising. */</span>
<span style="color: #000000">bleprph_advertise</span>();
}
<span style="color: #A90D91">return</span> <span style="color: #1C01CE">0</span>;
<span style="color: #A90D91">case</span> <span style="color: #000000">BLE_GAP_EVENT_DISCONNECT</span>:
<span style="color: #000000">BLEPRPH_LOG</span>(<span style="color: #000000">INFO</span>, <span style="color: #C41A16">&quot;disconnect; reason=%d &quot;</span>, <span style="color: #000000">event-&gt;disconnect</span>.<span style="color: #000000">reason</span>);
<span style="color: #000000">bleprph_print_conn_desc</span>(<span style="color: #000000">&amp;event-&gt;disconnect</span>.<span style="color: #000000">conn</span>);
<span style="color: #000000">BLEPRPH_LOG</span>(<span style="color: #000000">INFO</span>, <span style="color: #C41A16">&quot;\n&quot;</span>);
<span style="color: #177500">/* Connection terminated; resume advertising. */</span>
<span style="color: #000000">bleprph_advertise</span>();
<span style="color: #A90D91">return</span> <span style="color: #1C01CE">0</span>;
<span style="color: #A90D91">case</span> <span style="color: #000000">BLE_GAP_EVENT_CONN_UPDATE</span>:
<span style="color: #177500">/* The central has updated the connection parameters. */</span>
<span style="color: #000000">BLEPRPH_LOG</span>(<span style="color: #000000">INFO</span>, <span style="color: #C41A16">&quot;connection updated; status=%d &quot;</span>,
<span style="color: #000000">event-&gt;conn_update</span>.<span style="color: #000000">status</span>);
<span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_gap_conn_find</span>(<span style="color: #000000">event-&gt;connect</span>.<span style="color: #000000">conn_handle</span>, <span style="color: #000000">&amp;desc</span>);
<span style="color: #000000">assert</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
<span style="color: #000000">bleprph_print_conn_desc</span>(<span style="color: #000000">&amp;desc</span>);
<span style="color: #000000">BLEPRPH_LOG</span>(<span style="color: #000000">INFO</span>, <span style="color: #C41A16">&quot;\n&quot;</span>);
<span style="color: #A90D91">return</span> <span style="color: #1C01CE">0</span>;
<span style="color: #A90D91">case</span> <span style="color: #000000">BLE_GAP_EVENT_ENC_CHANGE</span>:
<span style="color: #177500">/* Encryption has been enabled or disabled for this connection. */</span>
<span style="color: #000000">BLEPRPH_LOG</span>(<span style="color: #000000">INFO</span>, <span style="color: #C41A16">&quot;encryption change event; status=%d &quot;</span>,
<span style="color: #000000">event-&gt;enc_change</span>.<span style="color: #000000">status</span>);
<span style="color: #000000">rc</span> <span style="color: #000000">=</span> <span style="color: #000000">ble_gap_conn_find</span>(<span style="color: #000000">event-&gt;connect</span>.<span style="color: #000000">conn_handle</span>, <span style="color: #000000">&amp;desc</span>);
<span style="color: #000000">assert</span>(<span style="color: #000000">rc</span> <span style="color: #000000">==</span> <span style="color: #1C01CE">0</span>);
<span style="color: #000000">bleprph_print_conn_desc</span>(<span style="color: #000000">&amp;desc</span>);
<span style="color: #000000">BLEPRPH_LOG</span>(<span style="color: #000000">INFO</span>, <span style="color: #C41A16">&quot;\n&quot;</span>);
<span style="color: #A90D91">return</span> <span style="color: #1C01CE">0</span>;
<span style="color: #A90D91">case</span> <span style="color: #000000">BLE_GAP_EVENT_SUBSCRIBE</span>:
<span style="color: #000000">BLEPRPH_LOG</span>(<span style="color: #000000">INFO</span>, <span style="color: #C41A16">&quot;subscribe event; conn_handle=%d attr_handle=%d &quot;</span>
<span style="color: #C41A16">&quot;reason=%d prevn=%d curn=%d previ=%d curi=%d\n&quot;</span>,
<span style="color: #000000">event-&gt;subscribe</span>.<span style="color: #000000">conn_handle</span>,
<span style="color: #000000">event-&gt;subscribe</span>.<span style="color: #000000">attr_handle</span>,
<span style="color: #000000">event-&gt;subscribe</span>.<span style="color: #000000">reason</span>,
<span style="color: #000000">event-&gt;subscribe</span>.<span style="color: #000000">prev_notify</span>,
<span style="color: #000000">event-&gt;subscribe</span>.<span style="color: #000000">cur_notify</span>,
<span style="color: #000000">event-&gt;subscribe</span>.<span style="color: #000000">prev_indicate</span>,
<span style="color: #000000">event-&gt;subscribe</span>.<span style="color: #000000">cur_indicate</span>);
<span style="color: #A90D91">return</span> <span style="color: #1C01CE">0</span>;
}
<span style="color: #A90D91">return</span> <span style="color: #1C01CE">0</span>;
}
</code></pre></div>
<p><br></p>
<p>Connection callbacks are used to communicate a variety of events related to a
connection. An application determines the type of event that occurred by
inspecting the value of the <em>event-&gt;type</em> parameter. The full list of event
codes can be found on the <a href="../../../network/ble/ble_hs/ble_gap/definitions/ble_gap_defs/">GAP events</a> page.</p>
<h4 id="guarantees">Guarantees</h4>
<p>It is important to know what your application code is allowed to do from within
a connection callback.</p>
<p><strong>No restrictions on NimBLE operations</strong></p>
<p>Your app is free to make calls into the NimBLE stack from within a connection
callback. <em>bleprph</em> takes advantage of this freedom when it resumes
advertising upon connection termination. All other NimBLE operations are also
allowed (service discovery, pairing initiation, etc).</p>
<p><strong>All context data is transient</strong></p>
<p>Pointers in the context object point to data living on the stack. Your
callback is free to read (or write, if appropriate) through these pointers, but
you should not store these pointers for later use. If your application needs
to retain some data from a context object, it needs to make a copy.</p>
<div class="row">
<ul class="nav nav-pills" style="margin-bottom: 10px">
<li>
</li>
<li class="pull-right">
</li>
</ul>
</div>
<footer class="row">
<div class="col-xs-12">
<p class="copyright">Apache Mynewt is available under Apache License, version 2.0.</p>
</div>
<div class="col-xs-12">
<div class="logos">
<a href="https://www.apache.org/">
<img src="/img/asf_logo_wide_small.png" alt="Apache" title="Apache">
</a>
<p>
Copyright © 2015-2021 The Apache Software Foundation.<br>
<small class="footnote">
Apache Mynewt, Mynewt, Apache, the Apache feather logo, and the Apache Mynewt
project logo are either registered trademarks or trademarks of the Apache
Software Foundation in the United States and other countries.
</small>
</p>
<a href="">
<img src="https://www.countit.com/images/add_to_slack.png" alt="Slack Icon" title="Join our Slack Community" />
</a>
</div>
</div>
<a href="https://www.apache.org/licenses/">
<button class="button-footer-asf">
License
</button>
</a>
<a href="https://www.apache.org/foundation/sponsorship.html">
<button class="button-footer-asf">
Sponsorship
</button>
</a>
<a href="https://www.apache.org/foundation/thanks.html">
<button class="button-footer-asf">
Thanks
</button>
</a>
<a href="https://www.apache.org/security/">
<button class="button-footer-asf">
Security
</button>
</a>
<a href="https://apache.org/events/current-event">
<button class="button-footer-asf">
ASF Events
</button>
</a>
</footer>
</div>
</div>
</div>
<script src="../../../../js/jquery-1.10.2.min.js"></script>
<script src="../../../../js/bootstrap-3.0.3.min.js"></script>
<script src="../../../../js/highlight.pack.js"></script>
<script src="../../../../js/base.js"></script>
<script src="../../../../js/custom.js"></script>
<script src="search/main.js"></script>
</body>
</html>