wsutil/codecs.h

   1 /** @file
   2  * codecs interface   2007 Tomas Kukosa
   3  *
   4  * Wireshark - Network traffic analyzer
   5  * By Gerald Combs <gerald@wireshark.org>
   6  * Copyright 1998 Gerald Combs
   7  *
   8  * SPDX-License-Identifier: GPL-2.0-or-later
   9  */
  10
  11 #ifndef _CODECS_H_
  12 #define _CODECS_H_
  13
  14 #include "ws_symbol_export.h"
  15 #include "ws_attributes.h"
  16
  17 #include <stdbool.h>
  18
  19 #include "wsutil/wmem/wmem_map.h"
  20
  21 #ifdef __cplusplus
  22 extern "C" {
  23 #endif /* __cplusplus */
  24
  25 typedef struct {
  26     void (*register_codec_module)(void);  /* routine to call to register a codec */
  27 } codecs_plugin;
  28
  29 WS_DLL_PUBLIC void codecs_register_plugin(const codecs_plugin *plug);
  30
  31 /**
  32  * For all built-in codecs and codec plugins, call their register routines.
  33  */
  34 WS_DLL_PUBLIC void codecs_init(void);
  35
  36 WS_DLL_PUBLIC void codecs_cleanup(void);
  37
  38 /**
  39  * Get compile-time information for libraries used by libwscodecs.
  40  */
  41 WS_DLL_PUBLIC void codec_get_compiled_version_info(GString *str);
  42
  43 struct codec_handle;
  44 typedef struct codec_handle *codec_handle_t;
  45
  46 typedef struct _codec_context_t {
  47     unsigned sample_rate;
  48     unsigned channels;
  49     wmem_map_t *fmtp_map;
  50     void *priv; /* Private state set by the decoder */
  51 } codec_context_t;
  52
  53 /*****************************************************************************/
  54 /* Interface which must be implemented by a codec */
  55 /* Codec decodes bytes to samples. Sample is 2 bytes! Codec writer must
  56  * be careful when API refers bytes and when samples and its counts.
  57  */
  58 /*****************************************************************************/
  59
  60 /** Initialize context of codec.
  61  * Context can contain any information required by codec to pass between calls
  62  * Note: There is just one codec context in runtime therefore no RTP stream
  63  * related information should be stored in the context!
  64  *
  65  * @return Pointer to codec context
  66  */
  67 typedef void *(*codec_init_fn)(codec_context_t *context);
  68
  69 /** Destroy context of codec
  70  *
  71  * @param context Pointer to codec context
  72  */
  73 typedef void (*codec_release_fn)(codec_context_t *context);
  74
  75 /** Get count of channels provided by the codec
  76  *
  77  * @param context Pointer to codec context
  78  *
  79  * @return Count of channels (e.g. 1)
  80  */
  81 typedef unsigned (*codec_get_channels_fn)(codec_context_t *context);
  82
  83 /** Get frequency/rate provided by the codec
  84  *
  85  * @param context Pointer to codec context
  86  *
  87  * @return Frequency (e.g. 8000)
  88  */
  89 typedef unsigned (*codec_get_frequency_fn)(codec_context_t *context);
  90
  91 /** Decode one frame of payload
  92  *  Function is called twice, with different values of parameters:
  93  *  (1) To query size of required buffer in bytes for decoded samples
  94  *      pointed by inputBytes:
  95  *      outputSamples or outputSamplesSize must be set NULL
  96  *  (2) To decode samples:
  97  *      outputSamples points to allocated memory, outputSamplesSize is set to
  98  *      value returned in step (1)
  99  *
 100  * @param context Pointer to codec context
 101  * @param inputBytes Pointer to input frame
 102  * @param inputBytesSize Length of input frame in bytes
 103  *        (count of bytes to decode)
 104  * @param outputSamples Pointer to output buffer with samples
 105  * @param outputSamplesSize Length of output buffer in bytes (not samples!)
 106  *        Function can override this value. All codecs set it to same value as it returns in (2) when (2) is called.
 107  *
 108  * @return Count of reqired bytes (!not samples) to allocate in (1) or
 109  *         Count of decoded bytes (!not samples) in (2)
 110  */
 111 typedef size_t (*codec_decode_fn)(codec_context_t *context,
 112         const void *inputBytes, size_t inputBytesSize,
 113         void *outputSamples, size_t *outputSamplesSize);
 114
 115 /*****************************************************************************/
 116 /* Codec registering interface */
 117 /*****************************************************************************/
 118
 119 WS_DLL_PUBLIC bool register_codec(const char *name, codec_init_fn init_fn,
 120         codec_release_fn release_fn, codec_get_channels_fn channels_fn,
 121         codec_get_frequency_fn frequency_fn, codec_decode_fn decode_fn);
 122 WS_DLL_PUBLIC bool deregister_codec(const char *name);
 123 WS_DLL_PUBLIC codec_handle_t find_codec(const char *name);
 124 WS_DLL_PUBLIC void *codec_init(codec_handle_t codec, codec_context_t *context);
 125 WS_DLL_PUBLIC void codec_release(codec_handle_t codec, codec_context_t *context);
 126 WS_DLL_PUBLIC unsigned codec_get_channels(codec_handle_t codec, codec_context_t *context);
 127 WS_DLL_PUBLIC unsigned codec_get_frequency(codec_handle_t codec, codec_context_t *context);
 128 WS_DLL_PUBLIC size_t codec_decode(codec_handle_t codec, codec_context_t *context,
 129         const void *inputBytes, size_t inputBytesSize,
 130         void *outputSamples, size_t *outputSamplesSize);
 131
 132 #ifdef __cplusplus
 133 }
 134 #endif /* __cplusplus */
 135
 136 #endif /* _CODECS_H_ */
 137
 138 /*
 139  * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
 140  *
 141  * Local variables:
 142  * c-basic-offset: 4
 143  * tab-width: 8
 144  * indent-tabs-mode: nil
 145  * End:
 146  *
 147  * vi: set shiftwidth=4 tabstop=8 expandtab:
 148  * :indentSize=4:tabSize=8:noTabs=true:
 149  */