OPAL  Version 3.14.3
opalplugin.h
Go to the documentation of this file.
1 /*
2  * opalplugins.h
3  *
4  * OPAL codec plugins handler
5  *
6  * Open Phone Abstraction Library (OPAL)
7  * Formally known as the Open H323 project.
8  *
9  * Copyright (C) 2004-2011 Post Increment
10  *
11  * Redistribution and use in source and binary forms, with or without
12  * modification, are permitted provided that the following conditions
13  * are met:
14  *
15  * - Redistributions of source code must retain the above copyright
16  * notice, this list of conditions and the following disclaimer.
17 
18  * - Redistributions in binary form must reproduce the above copyright
19  * notice, this list of conditions and the following disclaimer in the
20  * documentation and/or other materials provided with the distribution.
21  *
22  * - Neither the name of the Xiph.org Foundation nor the names of its
23  * contributors may be used to endorse or promote products derived from
24  * this software without specific prior written permission.
25  *
26  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
27  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
28  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
29  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
30  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
31  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
32  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
33  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
34  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
35  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
36  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37  *
38  * $Revision: 30580 $
39  * $Author: rjongbloed $
40  * $Date: 2013-09-30 11:20:54 +1000 (Mon, 30 Sep 2013) $
41  */
42 
43 #ifndef OPAL_CODEC_OPALPLUGIN_H
44 #define OPAL_CODEC_OPALPLUGIN_H
45 
46 #ifdef __cplusplus
47 extern "C" {
48 #endif
49 
50 #ifndef _CRT_NONSTDC_NO_DEPRECATE
51 #define _CRT_NONSTDC_NO_DEPRECATE 1
52 #endif
53 
54 #ifndef _CRT_SECURE_NO_WARNINGS
55 #define _CRT_SECURE_NO_WARNINGS 1
56 #endif
57 
58 #include <time.h>
59 
60 #ifdef _MSC_VER
61 #pragma warning(disable:4201)
62 #endif
63 
64 #ifdef _MSC_VER
65 # ifdef PLUGIN_CODEC_DLL_EXPORTS
66 # define PLUGIN_CODEC_DLL_API __declspec(dllexport)
67 # else
68 # define PLUGIN_CODEC_DLL_API __declspec(dllimport)
69 # endif
70 
71 #if !defined(strcasecmp) && !defined(_WIN32_WCE)
72 #define strcasecmp stricmp
73 #endif
74 
75 #else
76 
77 #define PLUGIN_CODEC_DLL_API
78 
79 #endif
80 
81 #ifdef PWLIB_PLUGIN_API_VERSION
82 #undef PWLIB_PLUGIN_API_VERSION
83 #endif
84 #define PWLIB_PLUGIN_API_VERSION 1
85 
86 #define PLUGIN_CODEC_VERSION_FIRST 1 // initial version
87 #define PLUGIN_CODEC_VERSION_WIDEBAND 2 // added wideband
88 #define PLUGIN_CODEC_VERSION_VIDEO 3 // added video
89 #define PLUGIN_CODEC_VERSION_FAX 4 // added fax
90 #define PLUGIN_CODEC_VERSION_OPTIONS 5 // added options handling
91 #define PLUGIN_CODEC_VERSION_INTERSECT 6 // added media option intersection merge functionality
92 #define PLUGIN_CODEC_VERSION_H245_DEF_GEN_PARAM 7 // added suppression of H.245 generic parameters via default
93 
94 #define PLUGIN_CODEC_VERSION PLUGIN_CODEC_VERSION_H245_DEF_GEN_PARAM // Always latest version
95 
96 #define PLUGIN_CODEC_API_VER_FN PWLibPlugin_GetAPIVersion
97 #define PLUGIN_CODEC_API_VER_FN_STR "PWLibPlugin_GetAPIVersion"
98 
99 #define PLUGIN_CODEC_GET_CODEC_FN OpalCodecPlugin_GetCodecs
100 #define PLUGIN_CODEC_GET_CODEC_FN_STR "OpalCodecPlugin_GetCodecs"
101 
102 #define PLUGIN_CODEC_API_VER_FN_DECLARE \
103 PLUGIN_CODEC_DLL_API unsigned int PLUGIN_CODEC_API_VER_FN() \
104 { return PWLIB_PLUGIN_API_VERSION; }
105 
106 enum {
107  PluginCodec_License_None = 0,
108  PluginCodec_Licence_None = PluginCodec_License_None, // allow for old code with misspelled constant
109  PluginCodec_License_GPL = 1,
110  PluginCodec_License_MPL = 2,
111  PluginCodec_License_Freeware = 3,
112  PluginCodec_License_ResearchAndDevelopmentUseOnly = 4,
113  PluginCodec_License_BSD = 5,
114  PluginCodec_License_LGPL = 6,
115 
116  PluginCodec_License_NoRoyalties = 0x7f,
117 
118  // any license codes above here require royalty payments
119  PluginCodec_License_RoyaltiesRequired = 0x80
120 };
121 
122 struct PluginCodec_information {
123  // start of version 1 fields
124  time_t timestamp_deprecated;
125 
126  const char * sourceAuthor; // source code author
127  const char * sourceVersion; // source code version
128  const char * sourceEmail; // source code email contact information
129  const char * sourceURL; // source code web site
130  const char * sourceCopyright; // source code copyright
131  const char * sourceLicense; // source code license
132  unsigned char sourceLicenseCode; // source code license
133 
134  const char * codecDescription; // codec description
135  const char * codecAuthor; // codec author
136  const char * codecVersion; // codec version
137  const char * codecEmail; // codec email contact information
138  const char * codecURL; // codec web site
139  const char * codecCopyright; // codec copyright information
140  const char * codecLicense; // codec license
141  unsigned short codecLicenseCode; // codec license code
142  // end of version 1 fields
143 
144  const char * timestamp; // String form of timestamp for plug in, generally as provided by __TIMESTAMP__
145 };
146 
147 enum PluginCodec_Flags {
148  PluginCodec_MediaTypeMask = 0x000f,
149  PluginCodec_MediaTypeAudio = 0x0000,
150  PluginCodec_MediaTypeVideo = 0x0001,
151  PluginCodec_MediaTypeAudioStreamed = 0x0002,
152  PluginCodec_MediaTypeFax = 0x0003,
153  PluginCodec_MediaTypeKnown = 0x000f, // Indicates use OPAL known media format
154 
155  PluginCodec_InputTypeMask = 0x0010,
156  PluginCodec_InputTypeRaw = 0x0000, // Note video is always RTP
157  PluginCodec_InputTypeRTP = 0x0010,
158 
159  PluginCodec_OutputTypeMask = 0x0020,
160  PluginCodec_OutputTypeRaw = 0x0000, // Note video is always RTP
161  PluginCodec_OutputTypeRTP = 0x0020,
162 
163  PluginCodec_RTPTypeMask = 0x0040, // Payload type number
164  PluginCodec_RTPTypeDynamic = 0x0000,
165  PluginCodec_RTPTypeExplicit = 0x0040,
166 
167  PluginCodec_RTPSharedMask = 0x0080,
168  PluginCodec_RTPTypeNotShared = 0x0000,
169  PluginCodec_RTPTypeShared = 0x0080,
170 
171  PluginCodec_DecodeSilenceMask = 0x0100,
172  PluginCodec_NoDecodeSilence = 0x0000,
173  PluginCodec_DecodeSilence = 0x0100,
174 
175  PluginCodec_EncodeSilenceMask = 0x0200,
176  PluginCodec_NoEncodeSilence = 0x0000,
177  PluginCodec_EncodeSilence = 0x0200,
178 
179  PluginCodec_MediaExtensionMask = 0x0400,
180  PluginCodec_MediaTypeExtVideo = 0x0400,
181 
182  PluginCodec_ComfortNoiseMask = 0x0800, // PluginCodec_MediaTypeAudio only
183  PluginCodec_ComfortNoise = 0x0800,
184 
185  PluginCodec_ErrorConcealmentMask = 0x0800, // PluginCodec_MediaTypeVideo only
186  PluginCodec_ErrorConcealment = 0x0800,
187 
188  PluginCodec_EmptyPayloadMask = 0x1000, // PluginCodec_MediaTypeAudio/PluginCodec_MediaTypeVideo only
189  PluginCodec_EmptyPayload = 0x1000,
190 
191  PluginCodec_OtherPayloadMask = 0x2000, // PluginCodec_MediaTypeAudio only
192  PluginCodec_OtherPayload = 0x2000,
193 
194  PluginCodec_BitsPerSamplePos = 12, // PluginCodec_MediaTypeAudioStreamed only
195  PluginCodec_BitsPerSampleMask = 0xf000,
196 
197  PluginCodec_ChannelsPos = 16,
198  PluginCodec_ChannelsMask = 0x003f0000
199 };
200 
201 #define PluginCodec_SetChannels(n) (((n-1)<<PluginCodec_ChannelsPos)&PluginCodec_ChannelsMask)
202 
203 
204 enum PluginCodec_CoderFlags {
205  PluginCodec_CoderSilenceFrame = 1, // request audio codec to create silence frame
206  PluginCodec_CoderForceIFrame = 2, // request video codec to force I frame
207  PluginCodec_CoderPacketLoss = 4 // indicate to video codec packets were lost
208 };
209 
210 enum PluginCodec_ReturnCoderFlags {
211  PluginCodec_ReturnCoderLastFrame = 1, // indicates when video codec returns last data for frame
212  PluginCodec_ReturnCoderIFrame = 2, // indicates when video returns I frame
213  PluginCodec_ReturnCoderRequestIFrame = 4, // indicates when video decoder request I frame for resync
214  PluginCodec_ReturnCoderBufferTooSmall = 8 // indicates when output buffer is not large enough to receive
215  // the data, another call to get_output_data_size is required
216 };
217 
218 struct PluginCodec_Definition;
219 
220 // Control function names
221 
222 #define PLUGINCODEC_CONTROL_VALID_FOR_PROTOCOL "valid_for_protocol"
223 #define PLUGINCODEC_CONTROL_GET_CODEC_OPTIONS "get_codec_options"
224 #define PLUGINCODEC_CONTROL_FREE_CODEC_OPTIONS "free_codec_options"
225 #define PLUGINCODEC_CONTROL_GET_OUTPUT_DATA_SIZE "get_output_data_size"
226 #define PLUGINCODEC_CONTROL_SET_CODEC_OPTIONS "set_codec_options"
227 #define PLUGINCODEC_CONTROL_GET_ACTIVE_OPTIONS "get_active_options"
228 #define PLUGINCODEC_CONTROL_TO_NORMALISED_OPTIONS "to_normalised_options"
229 #define PLUGINCODEC_CONTROL_TO_CUSTOMISED_OPTIONS "to_customised_options"
230 #define PLUGINCODEC_CONTROL_SET_INSTANCE_ID "set_instance_id"
231 #define PLUGINCODEC_CONTROL_SET_LOG_FUNCTION "set_log_function"
232 #define PLUGINCODEC_CONTROL_GET_STATISTICS "get_statistics"
233 #define PLUGINCODEC_CONTROL_TERMINATE_CODEC "terminate_codec"
234 
235 
236 /* Log function, plug in gets a pointer to this function which allows
237  it to use the standard OPAL logging system. The function returns 0 if
238  no logging was performed due to the log level. Note if log == NULL
239  then this return state is all that happens, so this may be executed
240  first to prevent lengthy logs that would not result in any output. */
241 typedef int (*PluginCodec_LogFunction)(unsigned level,
242  const char * file,
243  unsigned line,
244  const char * section,
245  const char * log);
246 
247 
248 struct PluginCodec_ControlDefn {
249  const char * name;
250  int (*control)(const struct PluginCodec_Definition * codec, void * context,
251  const char * name, void * parm, unsigned * parmLen);
252 
253 };
254 
255 enum PluginCodec_OptionTypes {
256  PluginCodec_StringOption,
257  PluginCodec_BoolOption,
258  PluginCodec_IntegerOption,
259  PluginCodec_RealOption,
260  PluginCodec_EnumOption,
261  PluginCodec_OctetsOption,
262  PluginCodec_NumOptionTypes,
263 };
264 
265 enum PluginCodec_OptionMerge {
266  PluginCodec_NoMerge,
267  PluginCodec_MinMerge,
268  PluginCodec_MaxMerge,
269  PluginCodec_EqualMerge,
270  PluginCodec_NotEqualMerge,
271  PluginCodec_AlwaysMerge,
272  PluginCodec_CustomMerge,
273  PluginCodec_IntersectionMerge,
274 
275  PluginCodec_AndMerge = PluginCodec_MinMerge,
276  PluginCodec_OrMerge = PluginCodec_MaxMerge
277 };
278 
279 #define PluginCodec_H245_Collapsing 0x40000000
280 #define PluginCodec_H245_NonCollapsing 0x20000000
281 #define PluginCodec_H245_Unsigned32 0x10000000
282 #define PluginCodec_H245_BooleanArray 0x08000000
283 #define PluginCodec_H245_TCS 0x04000000
284 #define PluginCodec_H245_OLC 0x02000000
285 #define PluginCodec_H245_ReqMode 0x01000000
286 #define PluginCodec_H245_OrdinalMask 0x0000ffff
287 #define PluginCodec_H245_PositionMask 0x00ff0000
288 #define PluginCodec_H245_PositionShift 16
289 
290 typedef int (*PluginCodec_MergeFunction)(char ** result, const char * dest, const char * src);
291 typedef void (*PluginCodec_FreeFunction)(char * string);
292 
293 struct PluginCodec_Option {
294  // start of version 4 fields
295  enum PluginCodec_OptionTypes m_type;
296  const char * m_name;
297  unsigned m_readOnly;
298  enum PluginCodec_OptionMerge m_merge;
299  const char * m_value;
300  const char * m_FMTPName;
301  const char * m_FMTPDefault;
302  int m_H245Generic;
303  const char * m_minimum;
304  const char * m_maximum;
305  PluginCodec_MergeFunction m_mergeFunction; // Used if m_merge==PluginCodec_CustomMerge
306  PluginCodec_FreeFunction m_freeFunction;
307  const char * m_H245Default;
308 };
309 
310 
311 // Normalised option names
312 #define PLUGINCODEC_OPTION_NEEDS_JITTER "Needs Jitter"
313 #define PLUGINCODEC_OPTION_CLOCK_RATE "Clock Rate"
314 #define PLUGINCODEC_OPTION_CHANNELS "Channels"
315 #define PLUGINCODEC_OPTION_RTP_CLOCK_RATE "RTP Clock Rate"
316 #define PLUGINCODEC_OPTION_RTP_CHANNELS "RTP Channels"
317 #define PLUGINCODEC_OPTION_FRAME_TIME "Frame Time"
318 #define PLUGINCODEC_OPTION_MAX_FRAME_SIZE "Max Frame Size"
319 #define PLUGINCODEC_OPTION_MAX_TX_PACKET_SIZE "Max Tx Packet Size" /* Really max PAYLOAD size */
320 #define PLUGINCODEC_OPTION_MAX_BIT_RATE "Max Bit Rate"
321 #define PLUGINCODEC_OPTION_TARGET_BIT_RATE "Target Bit Rate"
322 #define PLUGINCODEC_OPTION_RATE_CONTROL_PERIOD "Rate Control Period"
323 #define PLUGINCODEC_OPTION_RX_FRAMES_PER_PACKET "Rx Frames Per Packet"
324 #define PLUGINCODEC_OPTION_TX_FRAMES_PER_PACKET "Tx Frames Per Packet"
325 #define PLUGINCODEC_OPTION_FRAME_WIDTH "Frame Width"
326 #define PLUGINCODEC_OPTION_FRAME_HEIGHT "Frame Height"
327 #define PLUGINCODEC_OPTION_MIN_RX_FRAME_WIDTH "Min Rx Frame Width"
328 #define PLUGINCODEC_OPTION_MIN_RX_FRAME_HEIGHT "Min Rx Frame Height"
329 #define PLUGINCODEC_OPTION_MAX_RX_FRAME_WIDTH "Max Rx Frame Width"
330 #define PLUGINCODEC_OPTION_MAX_RX_FRAME_HEIGHT "Max Rx Frame Height"
331 #define PLUGINCODEC_OPTION_TEMPORAL_SPATIAL_TRADE_OFF "Temporal Spatial Trade Off"
332 #define PLUGINCODEC_OPTION_TX_KEY_FRAME_PERIOD "Tx Key Frame Period"
333 #define PLUGINCODEC_OPTION_VOICE_ACTIVITY_DETECT "VAD"
334 
335 #define PLUGINCODEC_OPTION_PROTOCOL "Protocol"
336 #define PLUGINCODEC_OPTION_PROTOCOL_H323 "H.323"
337 #define PLUGINCODEC_OPTION_PROTOCOL_SIP "SIP"
338 
339 
340 // Full definition of the codec
341 
342 struct PluginCodec_Definition {
343  unsigned int version; // codec structure version
344 
345  // start of version 1 fields
346  const struct PluginCodec_information * info; // license information
347 
348  unsigned int flags; // b0-3: 0 = audio, 1 = video
349  // b4: 0 = raw input, 1 = RTP input
350  // b5: 0 = raw output, 1 = RTP output
351  // b6: 0 = dynamic RTP, 1 = explicit RTP
352  // b7: 0 = no share RTP, 1 = share RTP
353 
354  const char * descr; // text decription
355 
356  const char * sourceFormat; // source format
357  const char * destFormat; // destination format
358 
359  const void * userData; // user data value
360 
361  unsigned int sampleRate; // samples per second
362  unsigned int bitsPerSec; // raw bits per second
363  unsigned int usPerFrame; // microseconds per frame
364 
365  union _parm {
366  struct _audio {
367  unsigned int samplesPerFrame; // audio: samples per frame
368  unsigned int bytesPerFrame; // audio: max bytes per frame
369  unsigned int recommendedFramesPerPacket; // audio: recommended number of frames per packet
370  unsigned int maxFramesPerPacket; // audio: maximum number of frames per packet
371  } audio;
372  struct _video {
373  unsigned int maxFrameWidth; // video: frame width
374  unsigned int maxFrameHeight; // video: frame height
375  unsigned int recommendedFrameRate; // video: recommended frame rate
376  unsigned int maxFrameRate; // video: max frame rate
377  } video;
378  } parm;
379 
380  unsigned char rtpPayload; // IANA RTP payload code (if defined)
381  const char * sdpFormat; // SDP format string (or NULL, if no SDP format)
382 
383  void * (*createCodec)(const struct PluginCodec_Definition * codec); // create codec
384  void (*destroyCodec) (const struct PluginCodec_Definition * codec, void * context); // destroy codec
385  int (*codecFunction) (const struct PluginCodec_Definition * codec, void * context, // do codec function
386  const void * from, unsigned * fromLen,
387  void * to, unsigned * toLen,
388  unsigned int * flag);
389  struct PluginCodec_ControlDefn * codecControls;
390 
391  // H323 specific fields
392  unsigned char h323CapabilityType;
393  const void * h323CapabilityData;
394 
395  // end of version 1 fields
396 
397  // NOTE!!!!! Due to an error in judgement, you cannot add ANY more fields
398  // to this structure without an API version change!!!!
399 };
400 
401 typedef const struct PluginCodec_Definition * (* PluginCodec_GetCodecFunction)(unsigned int *, unsigned int);
402 typedef unsigned (* PluginCodec_GetAPIVersionFunction)();
403 
404 
406 
407 #define PLUGINCODEC_RAW_AUDIO "L16"
408 #define PLUGINCODEC_RAW_VIDEO "YUV420P"
409 #define PLUGINCODEC_VIDEO_CLOCK 90000
410 #define PLUGINCODEC_MAX_FRAME_RATE 30
411 
412 #define PLUGINCODEC_CIF_WIDTH 352
413 #define PLUGINCODEC_CIF_HEIGHT 288
414 
415 #define PLUGINCODEC_CIF4_WIDTH (PLUGINCODEC_CIF_WIDTH*2)
416 #define PLUGINCODEC_CIF4_HEIGHT (PLUGINCODEC_CIF_HEIGHT*2)
417 
418 #define PLUGINCODEC_CIF16_WIDTH (PLUGINCODEC_CIF_WIDTH*4)
419 #define PLUGINCODEC_CIF16_HEIGHT (PLUGINCODEC_CIF_HEIGHT*4)
420 
421 #define PLUGINCODEC_QCIF_WIDTH (PLUGINCODEC_CIF_WIDTH/2)
422 #define PLUGINCODEC_QCIF_HEIGHT (PLUGINCODEC_CIF_HEIGHT/2)
423 
424 #define PLUGINCODEC_QCIF4_WIDTH (PLUGINCODEC_CIF4_WIDTH/2)
425 #define PLUGINCODEC_QCIF4_HEIGHT (PLUGINCODEC_CIF4_HEIGHT/2)
426 
427 #define PLUGINCODEC_SQCIF_WIDTH 128
428 #define PLUGINCODEC_SQCIF_HEIGHT 96
429 
430 
431 #ifndef __TIMESTAMP__
432 #define __TIMESTAMP__ "0"
433 #endif
434 
435 #define PLUGINCODEC_LICENSE(p1,p2,p3,p4,p5,p6,p7,p8,p9,p10,p11,p12,p13,p14,p15) \
436  static struct PluginCodec_information MyLicenseInfo = { 0,p1,p2,p3,p4,p5,p6,p7,p8,p9,p10,p11,p12,p13,p14,p15,__TIMESTAMP__ }
437 
438 
440 #define PLUGINCODEC_CODEC_PAIR(MediaFormat, \
441  PayloadName, \
442  Description, \
443  SampleRate, \
444  BitsPerSecond, \
445  FrameTime, \
446  p1,p2,p3,p4, \
447  PayloadType, \
448  H323type, \
449  H323data, \
450  CreateEncoder, \
451  DestroyEncoder, \
452  EncodeMedia, \
453  CreateDecoder, \
454  DestroyDecoder, \
455  DecodeMedia, \
456  ControlsTable, \
457  Flags, \
458  RawFormat, \
459  UserData \
460  ) \
461  { \
462  PLUGIN_CODEC_VERSION, &MyLicenseInfo, Flags, Description, RawFormat, MediaFormat, UserData, \
463  SampleRate, BitsPerSecond, FrameTime, {{ p1,p2,p3,p4 }}, PayloadType, PayloadName, \
464  CreateEncoder, DestroyEncoder, EncodeMedia, ControlsTable, H323type, H323data \
465  }, \
466  { \
467  PLUGIN_CODEC_VERSION, &MyLicenseInfo, Flags, Description, MediaFormat, RawFormat, UserData, \
468  SampleRate, BitsPerSecond, FrameTime, {{ p1,p2,p3,p4 }}, PayloadType, PayloadName, \
469  CreateDecoder, DestroyDecoder, DecodeMedia, ControlsTable, H323type, H323data \
470  }
471 
472 #define PLUGINCODEC_AUDIO_CODEC(MediaFormat, \
473  PayloadName, \
474  Description, \
475  SampleRate, \
476  BitsPerSecond, \
477  SamplesPerFrame, \
478  RecFramesPerPacket, \
479  MaxFramesPerPacket, \
480  RtpFlags, \
481  PayloadType, \
482  H323type, \
483  H323data, \
484  CreateEncoder, \
485  DestroyEncoder, \
486  EncodeAudio, \
487  CreateDecoder, \
488  DestroyDecoder, \
489  DecodeAudio, \
490  ControlsTable \
491  ) \
492  PLUGINCODEC_CODEC_PAIR(MediaFormat, \
493  PayloadName, \
494  Description, \
495  SampleRate, \
496  BitsPerSecond, \
497  (SamplesPerFrame)*1000000/(SampleRate), \
498  SamplesPerFrame, \
499  (BitsPerSecond)*(SampleRate)/(SamplesPerFrame)/8, \
500  RecFramesPerPacket, \
501  MaxFramesPerPacket, \
502  PayloadType, \
503  H323type, \
504  H323data, \
505  CreateEncoder, \
506  DestroyEncoder, \
507  EncodeAudio, \
508  CreateDecoder, \
509  DestroyDecoder, \
510  DecodeAudio, \
511  ControlsTable, \
512  PluginCodec_MediaTypeAudio | /* audio codec */ \
513  PluginCodec_InputTypeRaw | /* raw input data */ \
514  PluginCodec_OutputTypeRaw | /* raw output data */ \
515  (RtpFlags), \
516  PLUGINCODEC_RAW_AUDIO, \
517  NULL)
518 
519 #define PLUGINCODEC_ONE_AUDIO_CODEC(MediaFormat, \
520  PayloadName, \
521  Description, \
522  SampleRate, \
523  BitsPerSecond, \
524  SamplesPerFrame, \
525  RecFramesPerPacket, \
526  MaxFramesPerPacket, \
527  RtpFlags, \
528  PayloadType, \
529  H323type, \
530  H323data \
531  ) \
532  static struct PluginCodec_Definition CodecDefinitionTable[] = { \
533  PLUGINCODEC_AUDIO_CODEC(MediaFormat, \
534  PayloadName, \
535  Description, \
536  SampleRate, \
537  BitsPerSecond, \
538  SamplesPerFrame, \
539  RecFramesPerPacket, \
540  MaxFramesPerPacket, \
541  RtpFlags, \
542  PayloadType, \
543  H323type, \
544  H323data, \
545  MyCreateEncoder, \
546  MyDestroyEncoder, \
547  MyEncodeAudio, \
548  MyCreateDecoder, \
549  MyDestroyDecoder, \
550  MyDecodeAudio, \
551  MyControlsTable \
552  ) \
553  }
554 
555 #define PLUGINCODEC_VIDEO_CODEC(MediaFormat, \
556  PayloadName, \
557  Description, \
558  BitsPerSecond, \
559  MaxWidth, \
560  MaxHeight, \
561  RtpFlags, \
562  PayloadType, \
563  H323type, \
564  H323data, \
565  CreateEncoder, \
566  DestroyEncoder, \
567  EncodeVideo, \
568  CreateDecoder, \
569  DestroyDecoder, \
570  DecodeVideo, \
571  ControlsTable \
572  ) \
573  PLUGINCODEC_CODEC_PAIR(MediaFormat, \
574  PayloadName, \
575  Description, \
576  SampleRate, \
577  BitsPerSecond, \
578  1000000/PLUGINCODEC_MAX_FRAME_RATE, \
579  MaxWidth, \
580  MaxHeight, \
581  0,PLUGINCODEC_MAX_FRAME_RATE, \
582  PayloadType, \
583  H323type, \
584  H323data, \
585  CreateEncoder, \
586  DestroyEncoder, \
587  EncodeVideo, \
588  CreateDecoder, \
589  DestroyDecoder, \
590  DecodeVideo, \
591  ControlsTable, \
592  PluginCodec_MediaTypeVideo | /* video codec */ \
593  PluginCodec_InputTypeRTP | /* RTP input data */ \
594  PluginCodec_OutputTypeRTP | /* RTP output data */ \
595  (RtpFlags), \
596  PLUGINCODEC_RAW_VIDEO, \
597  NULL)
598 
599 #define PLUGINCODEC_ONE_VIDEO_CODEC(MediaFormat, \
600  PayloadName, \
601  Description, \
602  BitsPerSecond, \
603  MaxWidth, \
604  MaxHeight, \
605  RtpFlags, \
606  PayloadType, \
607  H323type, \
608  H323data \
609  ) \
610  static struct PluginCodec_Definition CodecDefinitionTable[] = { \
611  PLUGINCODEC_VIDEO_CODEC(MediaFormat, \
612  PayloadName, \
613  Description, \
614  BitsPerSecond, \
615  MaxWidth, \
616  MaxHeight, \
617  RtpFlags, \
618  PayloadType, \
619  H323type, \
620  H323data, \
621  CreateEncoder, \
622  DestroyEncoder, \
623  EncodeAudio, \
624  CreateDecoder, \
625  DestroyDecoder, \
626  DecodeAudio, \
627  ControlsTable \
628  ) \
629  }
630 
631 
633 //
634 // H.323 specific values
635 //
636 
637 
638 struct PluginCodec_H323CapabilityExtension {
639  unsigned int index;
640  void * data;
641  unsigned dataLength;
642 };
643 
644 struct PluginCodec_H323NonStandardCodecData {
645  const char * objectId;
646  unsigned char t35CountryCode;
647  unsigned char t35Extension;
648  unsigned short manufacturerCode;
649  const unsigned char * data;
650  unsigned int dataLength;
651  int (*capabilityMatchFunction)(struct PluginCodec_H323NonStandardCodecData *);
652 };
653 
654 
655 struct PluginCodec_H323GenericParameterDefinition
656 {
657  /* The following used to be a simple integer for the collapsing flag in
658  version 3 and earlier. We hope that all those implementations just used
659  zero and one (a good bet) and thus the below bit fields will be backward
660  compatible, putting the parameter in all three PDU types.
661  */
662 #ifndef SOLARIS
663  struct {
664 #endif
665  int collapsing:1; /* boolean */
666  int excludeTCS:1;
667  int excludeOLC:1;
668  int excludeReqMode:1;
669  int readOnly:1;
670 #ifndef SOLARIS
671  };
672 #endif
673 
674  unsigned int id;
675 
676  enum PluginCodec_H323GenericParameterType {
677  /* these need to be in the same order as the choices in
678  H245_ParameterValue::Choices, as the value is just cast to that type
679  */
680  PluginCodec_GenericParameter_Logical = 0,
681  PluginCodec_GenericParameter_BooleanArray,
682  PluginCodec_GenericParameter_UnsignedMin,
683  PluginCodec_GenericParameter_UnsignedMax,
684  PluginCodec_GenericParameter_Unsigned32Min,
685  PluginCodec_GenericParameter_Unsigned32Max,
686  PluginCodec_GenericParameter_OctetString,
687  PluginCodec_GenericParameter_GenericParameter,
688 
689  PluginCodec_GenericParameter_logical = 0,
690  PluginCodec_GenericParameter_booleanArray,
691  PluginCodec_GenericParameter_unsignedMin,
692  PluginCodec_GenericParameter_unsignedMax,
693  PluginCodec_GenericParameter_unsigned32Min,
694  PluginCodec_GenericParameter_unsigned32Max,
695  PluginCodec_GenericParameter_octetString,
696  PluginCodec_GenericParameter_genericParameter
697  } type;
698 
699  union {
700  unsigned long integer;
701  const char * octetstring;
702  struct PluginCodec_H323GenericParameterDefinition *genericparameter;
703  } value;
704 };
705 
706 struct PluginCodec_H323GenericCodecData
707 {
708  // some cunning structures & lists, and associated logic in
709  // H323CodecPluginGenericAudioCapability::H323CodecPluginGenericAudioCapability()
710  const char * standardIdentifier;
711  unsigned int maxBitRate; // Zero means use value from OpalMediaFormat
712 
713  /* parameters; these are the parameters which are set in the
714  'TerminalCapabilitySet' and 'OpenLogicalChannel' requests */
715  unsigned int nParameters;
716  /* an array of nParameters parameter definitions */
717  const struct PluginCodec_H323GenericParameterDefinition *params;
718 };
719 
720 
721 struct PluginCodec_H323AudioGSMData {
722  int comfortNoise:1;
723  int scrambled:1;
724 };
725 
726 struct PluginCodec_H323AudioG7231AnnexC {
727  unsigned char maxAl_sduAudioFrames;
728  int silenceSuppression:1;
729  int highRateMode0:6; // INTEGER (27..78), -- units octets
730  int highRateMode1:6; // INTEGER (27..78), -- units octets
731  int lowRateMode0:6; // INTEGER (23..66), -- units octets
732  int lowRateMode1:6; // INTEGER (23..66), -- units octets
733  int sidMode0:4; // INTEGER (6..17), -- units octets
734  int sidMode1:4; // INTEGER (6..17), -- units octets
735 };
736 
737 
738 enum {
739  PluginCodec_H323Codec_undefined, // must be zero, so empty struct is undefined
740  PluginCodec_H323Codec_programmed, // H323ProgrammedCapability
741  PluginCodec_H323Codec_nonStandard, // H323NonStandardData
742  PluginCodec_H323Codec_generic, // H323GenericCodecData
743 
744  // audio codecs
745  PluginCodec_H323AudioCodec_g711Alaw_64k, // int
746  PluginCodec_H323AudioCodec_g711Alaw_56k, // int
747  PluginCodec_H323AudioCodec_g711Ulaw_64k, // int
748  PluginCodec_H323AudioCodec_g711Ulaw_56k, // int
749  PluginCodec_H323AudioCodec_g722_64k, // int
750  PluginCodec_H323AudioCodec_g722_56k, // int
751  PluginCodec_H323AudioCodec_g722_48k, // int
752  PluginCodec_H323AudioCodec_g7231, // H323AudioG7231Data
753  PluginCodec_H323AudioCodec_g728, // int
754  PluginCodec_H323AudioCodec_g729, // int
755  PluginCodec_H323AudioCodec_g729AnnexA, // int
756  PluginCodec_H323AudioCodec_is11172, // not yet implemented
757  PluginCodec_H323AudioCodec_is13818Audio, // not yet implemented
758  PluginCodec_H323AudioCodec_g729wAnnexB, // int
759  PluginCodec_H323AudioCodec_g729AnnexAwAnnexB, // int
760  PluginCodec_H323AudioCodec_g7231AnnexC, // H323AudioG7231AnnexC
761  PluginCodec_H323AudioCodec_gsmFullRate, // H323AudioGSMData
762  PluginCodec_H323AudioCodec_gsmHalfRate, // H323AudioGSMData
763  PluginCodec_H323AudioCodec_gsmEnhancedFullRate, // H323AudioGSMData
764  PluginCodec_H323AudioCodec_g729Extensions, // not yet implemented
765 
766  // video codecs
767  PluginCodec_H323VideoCodec_h261, // implemented
768  PluginCodec_H323VideoCodec_h262, // not yet implemented
769  PluginCodec_H323VideoCodec_h263, // implemented
770  PluginCodec_H323VideoCodec_is11172, // not yet implemented
771 
772  // other capabilities
773  PluginCodec_H323VideoCodec_Extended, // implemented (for use with H.239)
774  PluginCodec_H323T38Codec, // not yet implemented
775 
776  // special codes
777  PluginCodec_H323Codec_NoH323 = 0xff, // used for SIP-only codecs
778 };
779 
781 //
782 // Generic Codec Standard Identifiers
783 //
784 
785 // Audio Capabilities
786 // AMR (as defined in H.245v13 Annex I)
787 #define OpalPluginCodec_Identifer_AMR "0.0.8.245.1.1.1"
788 #define PLUGINCODEC_OPTION_OCTET_ALIGNED "Octet Aligned"
789 
790 
791 // AMR-NB\WB (as defined in H.245v13 Annex R)
792 #define OpalPluginCodec_Identifer_AMR_NB "0.0.8.245.1.1.9"
793 #define OpalPluginCodec_Identifer_AMR_WB "0.0.8.245.1.1.10"
794 
795 // G.722.1
796 #define OpalPluginCodec_Identifer_G7221 "0.0.7.7221.1.0"
797 #define OpalPluginCodec_Identifer_G7221ext "0.0.7.7221.1.1.0"
798 
799 // G.722.2 (aka AMR-WB)
800 #define OpalPluginCodec_Identifer_G7222 "0.0.7.7222.1.0"
801 
802 // iLBC (as defined in H.245v13 Annex S)
803 #define OpalPluginCodec_Identifer_iLBC "0.0.8.245.1.1.11"
804 
805 
806 // Video Capabilities
807 
808 #define PLUGINCODEC_OPTION_PROFILE "Profile"
809 #define PLUGINCODEC_OPTION_SIMPLE_PROFILE "Simple"
810 #define PLUGINCODEC_OPTION_LEVEL "Level"
811 
812 // H264 (as defined in H.241)
813 #define OpalPluginCodec_Identifer_H264_Aligned "0.0.8.241.0.0.0.0"
814 #define OpalPluginCodec_Identifer_H264_NonInterleaved "0.0.8.241.0.0.0.1"
815 #define OpalPluginCodec_Identifer_H264_Interleaved "0.0.8.241.0.0.0.2"
816 #define OpalPluginCodec_Identifer_H264_Generic "0.0.8.241.0.0.1"
817 #define PLUGINCODEC_OPTION_MAX_NALU_SIZE "Max NALU Size"
818 #define PLUGINCODEC_OPTION_H264_PACKET_MODE "Packetization Mode"
819 
820 // ISO/IEC 14496-2 MPEG4 part 2 (as defined in H.245v13 Annex E)
821 #define OpalPluginCodec_Identifer_MPEG4 "0.0.8.245.1.0.0"
822 #define PLUGINCODEC_OPTION_MPEG4_ADV_SIMPLE_PROFILE "Advanced Simple"
823 #define PLUGINCODEC_OPTION_MPEG4_DECODER_CONFIG "DCI"
824 
825 
827 //
828 // Predefined options for H.323 codecs
829 //
830 
831 #define PLUGINCODEC_SQCIF_MPI "SQCIF MPI"
832 #define PLUGINCODEC_QCIF_MPI "QCIF MPI"
833 #define PLUGINCODEC_CIF_MPI "CIF MPI"
834 #define PLUGINCODEC_CIF4_MPI "CIF4 MPI"
835 #define PLUGINCODEC_CIF16_MPI "CIF16 MPI"
836 #define PLUGINCODEC_CUSTOM_MPI "Custom MPI"
837 
838 #define PLUGINCODEC_MPI_DISABLED 33
839 
840 #define PLUGINCODEC_MEDIA_PACKETIZATION "Media Packetization"
841 #define PLUGINCODEC_MEDIA_PACKETIZATIONS "Media Packetizations"
842 
843 #define H261_ANNEX_D "Annex D - Still Image Transmit"
844 #define H263_ANNEX_D "Annex D - Unrestricted Motion Vector"
845 #define H263_ANNEX_F "Annex F - Advanced Prediction"
846 #define H263_ANNEX_I "Annex I - Advanced INTRA Coding"
847 #define H263_ANNEX_J "Annex J - Deblocking Filter"
848 #define H263_ANNEX_K "Annex K - Slice Structure"
849 #define H263_ANNEX_N "Annex N - Reference Picture Selection"
850 #define H263_ANNEX_S "Annex S - Alternative INTER VLC"
851 #define H263_ANNEX_T "Annex T - Modified Quantization"
852 
853 #ifndef STRINGIZE
854 #define __INTERNAL_STRINGIZE__(v) #v
855 #define STRINGIZE(v) __INTERNAL_STRINGIZE__(v)
856 #endif
857 
858 
860 //
861 // RTP specific definitions
862 //
863 
864 #define PluginCodec_RTP_MaxPacketSize (1518-14-4-8-20-16) // Max Ethernet packet (1518 bytes) minus 802.3/CRC, 802.3, IP, UDP headers
865 #define PluginCodec_RTP_MinHeaderSize (12)
866 #define PluginCodec_RTP_MaxPayloadSize (PluginCodec_RTP_MaxPacketSize - PluginCodec_RTP_MinHeaderSize)
867 
868 #define PluginCodec_RTP_GetWORD(ptr, off) ((((unsigned char*)(ptr))[off] << 8) | ((unsigned char*)(ptr))[off+1])
869 
870 #define PluginCodec_RTP_GetDWORD(ptr, off) ((((unsigned char*)(ptr))[off ] << 24)|\
871  (((unsigned char*)(ptr))[off+1] << 16)|\
872  (((unsigned char*)(ptr))[off+2] << 8 )|\
873  ((unsigned char*)(ptr))[off+3])
874 
875 #define PluginCodec_RTP_SetWORD(ptr, off, val) ((((unsigned char*)(ptr))[off ] = (unsigned char)((val) >> 8 )),\
876  (((unsigned char*)(ptr))[off+1] = (unsigned char) (val) ))
877 
878 #define PluginCodec_RTP_SetDWORD(ptr, off, val) ((((unsigned char*)(ptr))[off ] = (unsigned char)((val) >> 24)),\
879  (((unsigned char*)(ptr))[off+1] = (unsigned char)((val) >> 16)),\
880  (((unsigned char*)(ptr))[off+2] = (unsigned char)((val) >> 8 )),\
881  (((unsigned char*)(ptr))[off+3] = (unsigned char) (val) ))
882 
883 #define PluginCodec_RTP_GetCSRCHdrLength(ptr) ((((unsigned char*)(ptr))[0] & 0x0f)*4 + PluginCodec_RTP_MinHeaderSize)
884 #define PluginCodec_RTP_GetExtHdrLength(ptr) ((((unsigned char*)(ptr))[0] & 0x10) ? (PluginCodec_RTP_GetWORD(ptr, PluginCodec_RTP_GetCSRCHdrLength(ptr)+2)*4+4) : 0)
885 
886 #define PluginCodec_RTP_GetHeaderLength(ptr) (PluginCodec_RTP_GetCSRCHdrLength(ptr) + PluginCodec_RTP_GetExtHdrLength(ptr))
887 #define PluginCodec_RTP_GetPayloadPtr(ptr) ((unsigned char*)(ptr) + PluginCodec_RTP_GetHeaderLength(ptr))
888 #define PluginCodec_RTP_GetPayloadType(ptr) (((unsigned char*)(ptr))[1] & 0x7f)
889 #define PluginCodec_RTP_SetPayloadType(ptr, type) (((unsigned char*)(ptr))[1] = (unsigned char)((((unsigned char*)(ptr))[1] & 0x80) | (type & 0x7f)))
890 #define PluginCodec_RTP_GetMarker(ptr) ((((unsigned char*)(ptr))[1] & 0x80) != 0)
891 #define PluginCodec_RTP_SetMarker(ptr, mark) (((unsigned char*)(ptr))[1] = (unsigned char)((((unsigned char*)(ptr))[1] & 0x7f) | (mark != 0 ? 0x80 : 0)))
892 #define PluginCodec_RTP_GetTimestamp(ptr) PluginCodec_RTP_GetDWORD(ptr, 4)
893 #define PluginCodec_RTP_SetTimestamp(ptr, ts) PluginCodec_RTP_SetDWORD(ptr, 4, ts)
894 #define PluginCodec_RTP_GetSequenceNumber(ptr) PluginCodec_RTP_GetWORD(ptr, 2)
895 #define PluginCodec_RTP_SetSequenceNumber(ptr, sn) PluginCodec_RTP_SetWORD(ptr, 2, sn)
896 #define PluginCodec_RTP_GetSSRC(ptr) PluginCodec_RTP_GetDWORD(ptr, 8)
897 #define PluginCodec_RTP_SetSSRC(ptr, ssrc) PluginCodec_RTP_SetDWORD(ptr, 8, ssrc)
898 
899 
900 
902 //
903 // video specific definitions
904 //
905 
906 struct PluginCodec_Video_FrameHeader {
907  unsigned int x;
908  unsigned int y;
909  unsigned int width;
910  unsigned int height;
911 };
912 
913 #ifdef __cplusplus
914 };
915 
916 inline unsigned char * OPAL_VIDEO_FRAME_DATA_PTR(struct PluginCodec_Video_FrameHeader * base)
917 { return (((unsigned char *)base) + sizeof(PluginCodec_Video_FrameHeader)); }
918 
919 inline unsigned char * OPAL_VIDEO_FRAME_DATA_PTR(const PluginCodec_Video_FrameHeader * base)
920 { return (((unsigned char *)base) + sizeof(PluginCodec_Video_FrameHeader)); }
921 
922 extern "C" {
923 #endif
924 
925 
927 //
928 // experimental definitions for statically linking codecs
929 //
930 
931 #ifdef OPAL_STATIC_CODEC
932 
933 # undef PLUGIN_CODEC_DLL_API
934 # define PLUGIN_CODEC_DLL_API static
935 # define PLUGIN_CODEC_IMPLEMENT(name) \
936 unsigned int Opal_StaticCodec_##name##_GetAPIVersion() \
937 { return PWLIB_PLUGIN_API_VERSION; } \
938 static const struct PluginCodec_Definition * PLUGIN_CODEC_GET_CODEC_FN(unsigned * count, unsigned /*version*/); \
939 struct const PluginCodec_Definition * Opal_StaticCodec_##name##_GetCodecs(unsigned * p1, unsigned p2) \
940 { return PLUGIN_CODEC_GET_CODEC_FN(p1,p2); } \
941 
942 # define PLUGIN_CODEC_IMPLEMENT_ALL(name, table, ver) \
943 unsigned int Opal_StaticCodec_##name##_GetAPIVersion() \
944 { return PWLIB_PLUGIN_API_VERSION; } \
945 PLUGIN_CODEC_DLL_API const struct PluginCodec_Definition * Opal_StaticCodec_##name##_GetCodecs(unsigned * count, unsigned version) \
946 { *count = sizeof(table)/sizeof(struct PluginCodec_Definition); return version < ver ? NULL : table; }
947 
948 
949 #else
950 
951 # define PLUGIN_CODEC_IMPLEMENT(name) \
952 PLUGIN_CODEC_DLL_API unsigned int PLUGIN_CODEC_API_VER_FN() \
953 { return PWLIB_PLUGIN_API_VERSION; } \
954 
955 # define PLUGIN_CODEC_IMPLEMENT_ALL(name, table, ver) \
956 PLUGIN_CODEC_IMPLEMENT(name) \
957 PLUGIN_CODEC_DLL_API const struct PluginCodec_Definition * PLUGIN_CODEC_GET_CODEC_FN(unsigned * count, unsigned version) \
958 { *count = sizeof(table)/sizeof(struct PluginCodec_Definition); return version < ver ? NULL : table; }
959 
960 
961 #endif
962 
963 #ifdef __cplusplus
964 };
965 #endif
966 
967 
968 #ifdef _MSC_VER
969 #pragma warning(default:4201)
970 #endif
971 
972 #endif // OPAL_CODEC_OPALPLUGIN_H