libcamera: request: Add cookie to make request tracking easier

Applications often have to map requests queued to a camera to external
resources. To make this easy, add a 64-bit integer cookie to the Request
class that is set when the request is created and can be retrieved at
any time, especially in the request completion handler. The cookie is
completely transparent for libcamera and is never modified.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>

1 files changed, 16 insertions, 2 deletions

diff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp
index f0b59858..8cf41a43 100644
--- a/src/libcamera/request.cpp
+++ b/src/libcamera/request.cpp
@@ -46,9 +46,17 @@ LOG_DEFINE_CATEGORY(Request)
 /**
  * \brief Create a capture request for a camera
  * \param[in] camera The camera that creates the request
+ * \param[in] cookie Opaque cookie for application use
+ *
+ * The \a cookie is stored in the request and is accessible through the
+ * cookie() method at any time. It is typically used by applications to map the
+ * request to an external resource in the request completion handler, and is
+ * completely opaque to libcamera.
+ *
  */
-Request::Request(Camera *camera)
-	: camera_(camera), controls_(camera), status_(RequestPending)
+Request::Request(Camera *camera, uint64_t cookie)
+	: camera_(camera), controls_(camera), cookie_(cookie),
+	  status_(RequestPending)
 {
 }
 
@@ -120,6 +128,12 @@ Buffer *Request::findBuffer(Stream *stream) const
 }
 
 /**
+ * \fn Request::cookie()
+ * \brief Retrieve the cookie set when the request was created
+ * \return The request cookie
+ */
+
+/**
  * \fn Request::status()
  * \brief Retrieve the request completion status
  *