Clean-up: modernize pretty_xml.cpp

[lttng-tools.git] / include / lttng / handle.h

diff --git a/include/lttng/handle.h b/include/lttng/handle.h
index c5958b4023e3b361a0496122a35e249435942b3f..08f9eaad965be23569ac500acfb6dd4206237551 100644 (file)
--- a/include/lttng/handle.h
+++ b/include/lttng/handle.h
@@ -1,65 +1,113 @@
 /*
- * Copyright (C) 2014 - David Goulet <dgoulet@efficios.com>
+ * Copyright (C) 2014 David Goulet <dgoulet@efficios.com>
  *
- * This library is free software; you can redistribute it and/or modify it
- * under the terms of the GNU Lesser General Public License, version 2.1 only,
- * as published by the Free Software Foundation.
+ * SPDX-License-Identifier: LGPL-2.1-only
  *
- * This library is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
- * for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this library; if not, write to the Free Software Foundation,
- * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  */
 
 #ifndef LTTNG_HANDLE_H
 #define LTTNG_HANDLE_H
 
 #include <lttng/domain.h>
+#include <lttng/lttng-export.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/*!
+@addtogroup api_session
+@{
+*/
+
 /*
  * Handle used as a context for commands.
  *
  * The structures should be initialized to zero before use.
  */
-#define LTTNG_HANDLE_PADDING1              16
+#define LTTNG_HANDLE_PADDING1 16
+
+/*!
+@brief
+    Recording session handle.
+
+Such a structure is a pair of a \ref api_session "recording session"
+name and a \ref api-channel-domain "tracing domain" summary.
+
+Some functions which accept a recording session handle parameter ignore
+the recording session name or the tracing domain summary.
+
+Create a recording session handle with lttng_create_handle().
+
+Destroy a recording session handle with lttng_destroy_handle().
+*/
 struct lttng_handle {
+       /// \ref api_session "Recording session" name.
        char session_name[LTTNG_NAME_MAX];
+
+       /// \ref api-channel-domain "Tracing domain" summary.
        struct lttng_domain domain;
 
        char padding[LTTNG_HANDLE_PADDING1];
 };
 
-/*
- * Create an handle used as a context for every request made to the library.
- *
- * This handle contains the session name and domain on which the command will
- * be executed. A domain is basically a tracer like the kernel or user space.
- *
- * A NULL domain indicates that the handle is not bound to a specific domain.
- * This is mostly used for actions that apply on a session and not on a domain
- * (e.g lttng_set_consumer_url).
- *
- * Return a newly allocated handle that should be freed using
- * lttng_destroy_handle. On error, NULL is returned.
- */
-extern struct lttng_handle *lttng_create_handle(const char *session_name,
-               struct lttng_domain *domain);
+/*!
+@brief
+    Creates and returns a recording session handle from the
+    \ref api_session "recording session" name
+    \lt_p{session_name} and the optional
+    \ref api-channel-domain "tracing domain" summary \lt_p{domain}.
 
-/*
- * Destroy an handle that has been previously created with lttng_create_handle.
- *
- * It free the given pointer making it unusable.
- */
-extern void lttng_destroy_handle(struct lttng_handle *handle);
+@param[in] session_name
+    @parblock
+    Recording session name part of the recording session handle to
+    create.
+
+    May be \c NULL.
+    @endparblock
+@param[in] domain
+    @parblock
+    Tracing domain summary part of the recording session handle to
+    create.
+
+    May be \c NULL.
+    @endparblock
+
+@returns
+    @parblock
+    New recording session handle.
+
+    Destroy the returned handle with lttng_destroy_handle().
+    @endparblock
+
+@sa lttng_destroy_handle() --
+    Destroys a recording session handle.
+*/
+LTTNG_EXPORT extern struct lttng_handle *lttng_create_handle(const char *session_name,
+                                                            struct lttng_domain *domain);
+
+/*!
+@brief
+    Destroys the recording session handle \lt_p{handle}.
+
+@note
+    @parblock
+    This function doesn't destroy the recording session named
+    \lt_p{handle->session_name}, but only the handle itself.
+
+    Use lttng_destroy_session_ext() to destroy a recording session.
+    @endparblock
+
+@param[in] handle
+    @parblock
+    Recording session handle to destroy.
+
+    May be \c NULL.
+    @endparblock
+*/
+LTTNG_EXPORT extern void lttng_destroy_handle(struct lttng_handle *handle);
 
+/// @}
 
 #ifdef __cplusplus
 }