/src/vlc/include/vlc_preparser_ipc.h

Source
// SPDX-License-Identifier: LGPL-2.1-or-later
/*****************************************************************************
 * vlc_preparser_serializer.h: preparser serializer
 *****************************************************************************
 * Copyright © 2025 Videolabs, VideoLAN and VLC authors
 *
 * Authors: Gabriel Lafond Thenaille <gabriel@videolabs.io>
 *****************************************************************************/

#ifndef VLC_PREPARSER_IPC_H
#define VLC_PREPARSER_IPC_H

#include <vlc_common.h>
#include <vlc_vector.h>
#include <vlc_input.h>
#include <vlc_input_item.h>
#include <vlc_preparser.h>
#include <vlc_interrupt.h>

/**
 * @defgroup preparser_ipc Preparser IPC
 * @ingroup preparser
 * @{
 * @file
 * VLC Preparser IPC API
 *
 * @defgroup preparser_msg preparser message api
 * @ingroup preparser_ipc
 * @{
 */

/**
 * Request types
 */
enum vlc_preparser_msg_req_type {
    /** 
     * Type of the request emitted by a `vlc_preparser_Push` call.
     */
    VLC_PREPARSER_MSG_REQ_TYPE_PARSE,
    /**
     * Type of the request emitted by a `vlc_preparser_GenerateThumbnail`
     * call.
     */
    VLC_PREPARSER_MSG_REQ_TYPE_THUMBNAIL,
    /**
     * Type of the request emitted by a
     * `vlc_preparser_GenerateThumbnailToFiles` call.
     */
    VLC_PREPARSER_MSG_REQ_TYPE_THUMBNAIL_TO_FILES,
};

/**
 * Preparser request.
 */
struct vlc_preparser_msg_req {
    /**
     * Type of the request.
     */
    enum vlc_preparser_msg_req_type type;

    /**
     * Used only by request of type `VLC_PREPARSER_MSG_REQ_TYPE_PARSE`.
     */
    int options;

    /**
     * Used by both type `VLC_PREPARSER_MSG_REQ_TYPE_THUMBNAIL` and
     * `VLC_PREPARSER_MSG_REQ_TYPE_THUMBNAIL_TO_FILES`.
     */
    struct vlc_thumbnailer_arg arg;

    /**
     * Used only by request of type
     * `VLC_PREPARSER_MSG_REQ_TYPE_THUMBNAIL_TO_FILES`.
     */
    /* all `output_path` will be freed so they must be heap allocated or set to
     * NULL before a `vlc_preparser_msg_Clean` call. */
    struct VLC_VECTOR(char *) outputs_path;
    struct VLC_VECTOR(struct vlc_thumbnailer_output) outputs;

    /* `uri` will be freed so it must be heap allocated or set to
     * NULL before a `vlc_preparser_msg_Clean` call. */
    char *uri;
};

/**
 * Preparser Response
 */
struct vlc_preparser_msg_res {
    /**
     * Type of the response (As the response answering a request they share the
     * same type).
     */
    enum vlc_preparser_msg_req_type type;

    /**
     * Used only by request of type `VLC_PREPARSER_MSG_REQ_TYPE_PARSE`.
     */
    struct VLC_VECTOR(input_attachment_t *) attachments;
    input_item_node_t *subtree;

    /**
     * Used only by request of type `VLC_PREPARSER_MSG_REQ_TYPE_THUMBNAIL`.
     */
    picture_t *pic;

    /**
     * Used only by request of type
     * `VLC_PREPARSER_MSG_REQ_TYPE_THUMBNAIL_TO_FILES`.
     */
    struct VLC_VECTOR(bool) result;

    /**
     * Used by all types of request.
     */
    int status;
    input_item_t *item;
};

/**
 * Preparser message.
 */
struct vlc_preparser_msg {
    /**
     * Type of the message can be a request or a response.
     */
    enum {
        VLC_PREPARSER_MSG_TYPE_REQ,
        VLC_PREPARSER_MSG_TYPE_RES,
    } type;

    /**
     * Type of the underling request or response.
     */
    enum vlc_preparser_msg_req_type req_type;
    union {
        struct vlc_preparser_msg_req req;
        struct vlc_preparser_msg_res res;
    };
};

/**
 * Initialize a preparser message.
 * 
 * @info    All data specific to each request/response have to be initialized 
 *          by hand.
 *
 * @param   msg         message to initialize.
 * @param   msg_type    message type (request or response).
 * @param   req_type    request/response type (see enum vlc_preparser_req_type
 *                      for more information).
 */
VLC_API void
vlc_preparser_msg_Init(struct vlc_preparser_msg *msg, int msg_type,
                       enum vlc_preparser_msg_req_type req_type);

/**
 * Clean all memory used by a message.
 * 
 * @info    This function don't free the `msg` pointer.
 *
 * @param   msg         message to release.
 */
VLC_API void
vlc_preparser_msg_Clean(struct vlc_preparser_msg *msg);

/**
 * @} preparser_msg
 *
 * @defgroup preparser_serdes preparser serializer api
 * @ingroup preparser_ipc
 *
 * @{
 */
#define VLC_PREPARSER_MSG_SERDES_TYPE_DATA              0x1
#define VLC_PREPARSER_MSG_SERDES_TYPE_ATTACHMENT        0x2
#define VLC_PREPARSER_MSG_SERDES_TYPE_END_DATA          0x4
#define VLC_PREPARSER_MSG_SERDES_TYPE_END_ATTACHMENT    0x8

struct vlc_preparser_msg_serdes_cbs {
    /**
     * Write callback.
     *
     * @param [in]  data        buffer to write.
     * @param [in]  size        number of bytes to write.
     * @param [in]  userdata    callback userdata.
     *
     * @return      the number of bytes writen or an error code on failure.
     */
    ssize_t (*write)(const void *data, size_t size, void *userdata);

    /**
     * Read callback.
     *
     * @param [out] data        buffer to read into.
     * @param [in]  size        number of bytes to read.
     * @param [in]  userdata    callback userdata.
     *
     * @return      the number of bytes read or an error code on failure.
     */
    ssize_t (*read)(void *data, size_t size, void *userdata);
};

struct vlc_preparser_msg_serdes;

struct vlc_preparser_msg_serdes_operations {
    /**
     * Serialize `msg` and call the write callback with serialized data.
     *
     * @param [in]  serdes      serializer internal structure.
     * @param [in]  msg         message to serialize.
     * @param [in]  userdata    context for the write callbacks
     *
     * @return      VLC_SUCCESS or an error code on failure.
     */
    int (*serialize)(struct vlc_preparser_msg_serdes *serdes,
                     const struct vlc_preparser_msg *msg,
                     void *userdata);

    /**
     * Deserialize `msg` and call the read callback to get data to deserialize.
     *
     * @param [in]  serdes      serializer internal structure.
     * @param [out] msg         message to deserialize.
     * @param [in]  userdata    context for the read callbacks
     *
     * @return      VLC_SUCCESS or an error code on failure.
     */
    int (*deserialize)(struct vlc_preparser_msg_serdes *serdes,
                       struct vlc_preparser_msg *msg,
                       void *userdata);

    /**
     * Close the serializer/deserialier and release all used memory.
     *
     * @param [in]  serdes  preparser msg serdes internal struture.
     */
    void (*close)(struct vlc_preparser_msg_serdes *serdes);
};

/**
 * Internal structure used by serializer.
 */
struct vlc_preparser_msg_serdes {
    /** Operations */
    const struct vlc_preparser_msg_serdes_operations *ops;

    struct {
        /** Callbacks */
        const struct vlc_preparser_msg_serdes_cbs *cbs;
        /** Used by the serializer module. */
        void *sys;
    } owner;
};

typedef int (*vlc_preparser_msg_serdes_module)
                (struct vlc_preparser_msg_serdes *, bool);

#define set_callback_preparser_msg_serdes(activate, priority) \
    {\
        vlc_preparser_msg_serdes_module open__ = activate;\
        (void)open__;\
        set_callback(activate)\
    }\
    set_capability("preparser msg serdes", priority)

/**
 * Call the serialize operation.
 *
 * @param [in]  s
 * @param [out] buf
 * @param [in]  msg
 *
 * @return      size of the allocated buffer.
 */
static inline int
vlc_preparser_msg_serdes_Serialize(struct vlc_preparser_msg_serdes *serdes,
                                   const struct vlc_preparser_msg *msg,
                                   void *userdata)
{
    assert(serdes != NULL);

    if (serdes->ops != NULL && serdes->ops->serialize != NULL) {
        return serdes->ops->serialize(serdes, msg, userdata);
    }
    return VLC_EGENERIC;
}

/**
 * Call the deserialize operation.
 *
 * @param [in]  s
 * @param [in]  buf
 * @param [in]  size
 *
 * @return      size of the allocated buffer.
 */
static inline int
vlc_preparser_msg_serdes_Deserialize(struct vlc_preparser_msg_serdes *serdes,
                                     struct vlc_preparser_msg *msg,
                                     void *userdata)
{
    assert(serdes!= NULL);

    if (serdes->ops != NULL && serdes->ops->deserialize != NULL) {
        return serdes->ops->deserialize(serdes, msg, userdata);
    }
    return VLC_EGENERIC;
}

/**
 * Free the msg_serdes struct.
 *
 * @param [in]  msg_serdes
 */
static inline void
vlc_preparser_msg_serdes_Delete(struct vlc_preparser_msg_serdes *serdes)
{
    assert(serdes != NULL);

    if (serdes->ops != NULL && serdes->ops->close != NULL) {
        serdes->ops->close(serdes);
    }
    free(serdes);
}

/**
 * Create a vlc_preparser_msg_serdes object and load a preparser msg_serdes
 * module.
 *
 * @param [in]  obj         vlc object
 * @param [in]  c           serializer's callbacks
 * @param [in]  bin_data    describe if the serializer and deserializer use 
 *                          binary data (intput_attachment_t or plane_t)
 *
 * @return      a vlc_preparser_msg_serdes object or NULL on failure.
 */
VLC_API struct vlc_preparser_msg_serdes *
vlc_preparser_msg_serdes_Create(vlc_object_t *obj,
                                const struct vlc_preparser_msg_serdes_cbs *c,
                                bool bin_data);

/**
 * @} preparser_serdes
 * @} preparser_ipc
 */

#endif /* VLC_PREPARSER_IPC */

Coverage Report

Created: 2026-02-05 06:37

Line	Count	Source
1		// SPDX-License-Identifier: LGPL-2.1-or-later
2		/*****************************************************************************
3		* vlc_preparser_serializer.h: preparser serializer
4		*****************************************************************************
5		* Copyright © 2025 Videolabs, VideoLAN and VLC authors
6		*
7		* Authors: Gabriel Lafond Thenaille <gabriel@videolabs.io>
8		*****************************************************************************/
9
10		#ifndef VLC_PREPARSER_IPC_H
11		#define VLC_PREPARSER_IPC_H
12
13		#include <vlc_common.h>
14		#include <vlc_vector.h>
15		#include <vlc_input.h>
16		#include <vlc_input_item.h>
17		#include <vlc_preparser.h>
18		#include <vlc_interrupt.h>
19
20		/**
21		* @defgroup preparser_ipc Preparser IPC
22		* @ingroup preparser
23		* @{
24		* @file
25		* VLC Preparser IPC API
26		*
27		* @defgroup preparser_msg preparser message api
28		* @ingroup preparser_ipc
29		* @{
30		*/
31
32		/**
33		* Request types
34		*/
35		enum vlc_preparser_msg_req_type {
36		/**
37		* Type of the request emitted by a `vlc_preparser_Push` call.
38		*/
39		VLC_PREPARSER_MSG_REQ_TYPE_PARSE,
40		/**
41		* Type of the request emitted by a `vlc_preparser_GenerateThumbnail`
42		* call.
43		*/
44		VLC_PREPARSER_MSG_REQ_TYPE_THUMBNAIL,
45		/**
46		* Type of the request emitted by a
47		* `vlc_preparser_GenerateThumbnailToFiles` call.
48		*/
49		VLC_PREPARSER_MSG_REQ_TYPE_THUMBNAIL_TO_FILES,
50		};
51
52		/**
53		* Preparser request.
54		*/
55		struct vlc_preparser_msg_req {
56		/**
57		* Type of the request.
58		*/
59		enum vlc_preparser_msg_req_type type;
60
61		/**
62		* Used only by request of type `VLC_PREPARSER_MSG_REQ_TYPE_PARSE`.
63		*/
64		int options;
65
66		/**
67		* Used by both type `VLC_PREPARSER_MSG_REQ_TYPE_THUMBNAIL` and
68		* `VLC_PREPARSER_MSG_REQ_TYPE_THUMBNAIL_TO_FILES`.
69		*/
70		struct vlc_thumbnailer_arg arg;
71
72		/**
73		* Used only by request of type
74		* `VLC_PREPARSER_MSG_REQ_TYPE_THUMBNAIL_TO_FILES`.
75		*/
76		/* all `output_path` will be freed so they must be heap allocated or set to
77		* NULL before a `vlc_preparser_msg_Clean` call. */
78		struct VLC_VECTOR(char *) outputs_path;
79		struct VLC_VECTOR(struct vlc_thumbnailer_output) outputs;
80
81		/* `uri` will be freed so it must be heap allocated or set to
82		* NULL before a `vlc_preparser_msg_Clean` call. */
83		char *uri;
84		};
85
86		/**
87		* Preparser Response
88		*/
89		struct vlc_preparser_msg_res {
90		/**
91		* Type of the response (As the response answering a request they share the
92		* same type).
93		*/
94		enum vlc_preparser_msg_req_type type;
95
96		/**
97		* Used only by request of type `VLC_PREPARSER_MSG_REQ_TYPE_PARSE`.
98		*/
99		struct VLC_VECTOR(input_attachment_t *) attachments;
100		input_item_node_t *subtree;
101
102		/**
103		* Used only by request of type `VLC_PREPARSER_MSG_REQ_TYPE_THUMBNAIL`.
104		*/
105		picture_t *pic;
106
107		/**
108		* Used only by request of type
109		* `VLC_PREPARSER_MSG_REQ_TYPE_THUMBNAIL_TO_FILES`.
110		*/
111		struct VLC_VECTOR(bool) result;
112
113		/**
114		* Used by all types of request.
115		*/
116		int status;
117		input_item_t *item;
118		};
119
120		/**
121		* Preparser message.
122		*/
123		struct vlc_preparser_msg {
124		/**
125		* Type of the message can be a request or a response.
126		*/
127		enum {
128		VLC_PREPARSER_MSG_TYPE_REQ,
129		VLC_PREPARSER_MSG_TYPE_RES,
130		} type;
131
132		/**
133		* Type of the underling request or response.
134		*/
135		enum vlc_preparser_msg_req_type req_type;
136		union {
137		struct vlc_preparser_msg_req req;
138		struct vlc_preparser_msg_res res;
139		};
140		};
141
142		/**
143		* Initialize a preparser message.
144		*
145		* @info All data specific to each request/response have to be initialized
146		* by hand.
147		*
148		* @param msg message to initialize.
149		* @param msg_type message type (request or response).
150		* @param req_type request/response type (see enum vlc_preparser_req_type
151		* for more information).
152		*/
153		VLC_API void
154		vlc_preparser_msg_Init(struct vlc_preparser_msg *msg, int msg_type,
155		enum vlc_preparser_msg_req_type req_type);
156
157		/**
158		* Clean all memory used by a message.
159		*
160		* @info This function don't free the `msg` pointer.
161		*
162		* @param msg message to release.
163		*/
164		VLC_API void
165		vlc_preparser_msg_Clean(struct vlc_preparser_msg *msg);
166
167		/**
168		* @} preparser_msg
169		*
170		* @defgroup preparser_serdes preparser serializer api
171		* @ingroup preparser_ipc
172		*
173		* @{
174		*/
175		#define VLC_PREPARSER_MSG_SERDES_TYPE_DATA 0x1
176		#define VLC_PREPARSER_MSG_SERDES_TYPE_ATTACHMENT 0x2
177		#define VLC_PREPARSER_MSG_SERDES_TYPE_END_DATA 0x4
178		#define VLC_PREPARSER_MSG_SERDES_TYPE_END_ATTACHMENT 0x8
179
180		struct vlc_preparser_msg_serdes_cbs {
181		/**
182		* Write callback.
183		*
184		* @param [in] data buffer to write.
185		* @param [in] size number of bytes to write.
186		* @param [in] userdata callback userdata.
187		*
188		* @return the number of bytes writen or an error code on failure.
189		*/
190		ssize_t (write)(const void data, size_t size, void *userdata);
191
192		/**
193		* Read callback.
194		*
195		* @param [out] data buffer to read into.
196		* @param [in] size number of bytes to read.
197		* @param [in] userdata callback userdata.
198		*
199		* @return the number of bytes read or an error code on failure.
200		*/
201		ssize_t (read)(void data, size_t size, void *userdata);
202		};
203
204		struct vlc_preparser_msg_serdes;
205
206		struct vlc_preparser_msg_serdes_operations {
207		/**
208		* Serialize `msg` and call the write callback with serialized data.
209		*
210		* @param [in] serdes serializer internal structure.
211		* @param [in] msg message to serialize.
212		* @param [in] userdata context for the write callbacks
213		*
214		* @return VLC_SUCCESS or an error code on failure.
215		*/
216		int (serialize)(struct vlc_preparser_msg_serdes serdes,
217		const struct vlc_preparser_msg *msg,
218		void *userdata);
219
220		/**
221		* Deserialize `msg` and call the read callback to get data to deserialize.
222		*
223		* @param [in] serdes serializer internal structure.
224		* @param [out] msg message to deserialize.
225		* @param [in] userdata context for the read callbacks
226		*
227		* @return VLC_SUCCESS or an error code on failure.
228		*/
229		int (deserialize)(struct vlc_preparser_msg_serdes serdes,
230		struct vlc_preparser_msg *msg,
231		void *userdata);
232
233		/**
234		* Close the serializer/deserialier and release all used memory.
235		*
236		* @param [in] serdes preparser msg serdes internal struture.
237		*/
238		void (close)(struct vlc_preparser_msg_serdes serdes);
239		};
240
241		/**
242		* Internal structure used by serializer.
243		*/
244		struct vlc_preparser_msg_serdes {
245		/** Operations */
246		const struct vlc_preparser_msg_serdes_operations *ops;
247
248		struct {
249		/** Callbacks */
250		const struct vlc_preparser_msg_serdes_cbs *cbs;
251		/** Used by the serializer module. */
252		void *sys;
253		} owner;
254		};
255
256		typedef int (*vlc_preparser_msg_serdes_module)
257		(struct vlc_preparser_msg_serdes *, bool);
258
259		#define set_callback_preparser_msg_serdes(activate, priority) \
260		{\
261		vlc_preparser_msg_serdes_module open__ = activate;\
262		(void)open__;\
263		set_callback(activate)\
264		}\
265		set_capability("preparser msg serdes", priority)
266
267		/**
268		* Call the serialize operation.
269		*
270		* @param [in] s
271		* @param [out] buf
272		* @param [in] msg
273		*
274		* @return size of the allocated buffer.
275		*/
276		static inline int
277		vlc_preparser_msg_serdes_Serialize(struct vlc_preparser_msg_serdes *serdes,
278		const struct vlc_preparser_msg *msg,
279		void *userdata)
280	0	{
281	0	assert(serdes != NULL);
282
283	0	if (serdes->ops != NULL && serdes->ops->serialize != NULL) {
284	0	return serdes->ops->serialize(serdes, msg, userdata);
285	0	}
286	0	return VLC_EGENERIC;
287	0	} Unexecuted instantiation: external.c:vlc_preparser_msg_serdes_Serialize Unexecuted instantiation: ipc.c:vlc_preparser_msg_serdes_Serialize
288
289		/**
290		* Call the deserialize operation.
291		*
292		* @param [in] s
293		* @param [in] buf
294		* @param [in] size
295		*
296		* @return size of the allocated buffer.
297		*/
298		static inline int
299		vlc_preparser_msg_serdes_Deserialize(struct vlc_preparser_msg_serdes *serdes,
300		struct vlc_preparser_msg *msg,
301		void *userdata)
302	0	{
303	0	assert(serdes!= NULL);
304
305	0	if (serdes->ops != NULL && serdes->ops->deserialize != NULL) {
306	0	return serdes->ops->deserialize(serdes, msg, userdata);
307	0	}
308	0	return VLC_EGENERIC;
309	0	} Unexecuted instantiation: external.c:vlc_preparser_msg_serdes_Deserialize Unexecuted instantiation: ipc.c:vlc_preparser_msg_serdes_Deserialize
310
311		/**
312		* Free the msg_serdes struct.
313		*
314		* @param [in] msg_serdes
315		*/
316		static inline void
317		vlc_preparser_msg_serdes_Delete(struct vlc_preparser_msg_serdes *serdes)
318	0	{
319	0	assert(serdes != NULL);
320
321	0	if (serdes->ops != NULL && serdes->ops->close != NULL) {
322	0	serdes->ops->close(serdes);
323	0	}
324	0	free(serdes);
325	0	} Unexecuted instantiation: external.c:vlc_preparser_msg_serdes_Delete Unexecuted instantiation: ipc.c:vlc_preparser_msg_serdes_Delete
326
327		/**
328		* Create a vlc_preparser_msg_serdes object and load a preparser msg_serdes
329		* module.
330		*
331		* @param [in] obj vlc object
332		* @param [in] c serializer's callbacks
333		* @param [in] bin_data describe if the serializer and deserializer use
334		* binary data (intput_attachment_t or plane_t)
335		*
336		* @return a vlc_preparser_msg_serdes object or NULL on failure.
337		*/
338		VLC_API struct vlc_preparser_msg_serdes *
339		vlc_preparser_msg_serdes_Create(vlc_object_t *obj,
340		const struct vlc_preparser_msg_serdes_cbs *c,
341		bool bin_data);
342
343		/**
344		* @} preparser_serdes
345		* @} preparser_ipc
346		*/
347
348		#endif /* VLC_PREPARSER_IPC */