gcoap: add api to forget a client-side observe request

sys/include/net/gcoap.h

@@ -1074,6 +1074,37 @@ int gcoap_obs_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
 size_t gcoap_obs_send(const uint8_t *buf, size_t len,
                       const coap_resource_t *resource);
 
+/**
+ * @brief   Forgets (invalidates) an existing observe request.
+ *
+ * This invalidates the internal (local) observe request state without actually
+ * sending a deregistration request to the server. Ths mechanism may be referred
+ * to as passive deregistration, as it does not send a deregistration request.
+ * This is implemented according to the description in RFC 7641,
+ * Section 3.6 (Cancellation): 'A client that is no longer interested in
+ * receiving notifications for a resource can simply "forget" the observation.'
+ * Successfully invalidating the request by calling this function guarantees
+ * that the corresponding observe response handler will not be called anymore.
+ *
+ * NOTE: There are cases were active deregistration is preferred instead.
+ * A server may continue sending notifications if it chooses to ignore the RST
+ * which is meant to indicate the client did not recognize the notification.
+ * For such server implementations this function must be called *before*
+ * sending an explicit deregister request (i.e., a GET request with the token
+ * of the registration and the observe option set to COAP_OBS_DEREGISTER).
+ * This will instruct the server to stop sending further notifications.
+ *
+ * @param[in] remote    remote endpoint that hosts the observed resource
+ * @param[in] token     token of the original GET request used for registering
+ *                      an observe
+ * @param[in] tokenlen  the length of the token in bytes
+ *
+ * @return  0 on success
+ * @return  < 0 on error
+ */
+int gcoap_obs_req_forget(const sock_udp_ep_t *remote, const uint8_t *token,
+                         size_t tokenlen);
+
 /**
  * @brief   Provides important operational statistics
  *

sys/net/application_layer/gcoap/gcoap.c

@@ -1535,6 +1535,23 @@ int gcoap_req_init_path_buffer(coap_pkt_t *pdu, uint8_t *buf, size_t len,
     return (res > 0) ? 0 : res;
 }
 
+int gcoap_obs_req_forget(const sock_udp_ep_t *remote, const uint8_t *token,
+                         size_t tokenlen) {
+    int res = -ENOENT;
+    gcoap_request_memo_t *obs_req_memo;
+    mutex_lock(&_coap_state.lock);
+    /* Find existing request memo of the observe */
+    obs_req_memo = _find_req_memo_by_token(remote, token, tokenlen);
+    if (obs_req_memo) {
+        /* forget the existing observe memo. */
+        obs_req_memo->state = GCOAP_MEMO_UNUSED;
+        res = 0;
+    }
+
+    mutex_unlock(&_coap_state.lock);
+    return res;
+}
+
 ssize_t gcoap_req_send_tl(const uint8_t *buf, size_t len,
                           const sock_udp_ep_t *remote,
                           gcoap_resp_handler_t resp_handler, void *context,