diff --git a/sys/include/net/gcoap.h b/sys/include/net/gcoap.h index 7b87cef560..8a3313de88 100644 --- a/sys/include/net/gcoap.h +++ b/sys/include/net/gcoap.h @@ -690,6 +690,16 @@ kernel_pid_t gcoap_init(void); /** * @brief Starts listening for resource paths * + * @pre @p listener is a valid pointer to a single listener (that is, + * `listener->next == NULL`) + * + * @note If you are tempted to register a pre-linked chain of listeners, + * consider placing all their resources in the resources array of a + * single listener instead. In the few cases where this does not work + * (that is, when the resources need a different `link_encoder` or other + * fields of the listener struct), they can just be registered + * individually. + * * @param[in] listener Listener containing the resources. */ void gcoap_register_listener(gcoap_listener_t *listener); diff --git a/sys/net/application_layer/gcoap/gcoap.c b/sys/net/application_layer/gcoap/gcoap.c index 3732fa3274..530ffdaa36 100644 --- a/sys/net/application_layer/gcoap/gcoap.c +++ b/sys/net/application_layer/gcoap/gcoap.c @@ -702,6 +702,10 @@ kernel_pid_t gcoap_init(void) void gcoap_register_listener(gcoap_listener_t *listener) { + /* That item will be overridden, ensure that the user expecting different + * behavior will notice this. */ + assert(listener->next == NULL); + if (!listener->link_encoder) { listener->link_encoder = gcoap_encode_link; }