CTR Pia  4.11.3
Game Communication Engine
chat_VoiceProtocol.h
1 /*---------------------------------------------------------------------------*
2  Project: Pia
3  File: chat_VoiceProtocol.h
4 
5  Copyright Nintendo. All rights reserved.
6 
7  These coded instructions, statements, and computer programs contain
8  proprietary information of Nintendo of America Inc. and/or Nintendo
9  Company Ltd., and are protected by Federal copyright law. They may
10  not be disclosed to third parties or copied or duplicated in any form,
11  in whole or in part, without the prior written consent of Nintendo.
12  *---------------------------------------------------------------------------*/
13 
14 
15 #pragma once
16 
17 #include <pia/transport/transport_definitions.h>
18 #include <pia/chat/chat_definitions.h>
19 
20 #include <pia/transport/transport_Protocol.h>
21 
22 #include <pia/common/common_CriticalSection.h>
23 
24 #pragma diag_suppress 1300
25 #include <nex.h>
26 #pragma diag_warning 1300
27 
28 // Forward declaration.
29 namespace nn
30 {
31 namespace pia
32 {
33 namespace transport
34 {
35 class UnreliableProtocol;
36 }
37 }
38 }
39 
40 struct VCTSession;
41 
42 #if NN_PIA_HF_LIBRARY
43 namespace nn
44 {
45 namespace pia
46 {
47 namespace chat
48 {
49 class HandsFree;
50 }
51 }
52 }
53 #endif
54 
55 
56 namespace nn
57 {
58 namespace pia
59 {
60 namespace chat
61 {
62 
63 
64 /*!
65 @brief Contains member functions that provide voice chat functionality.
66 
67 @details You cannot create more than one instance of <tt>VoiceProtocol</tt>.
68 
69 @date 2015-09-01 If the client specified for <tt>RemoveConferenceClient()</tt> cannot be found, the function now returns <tt>ResultNotFound</tt> instead of <tt>ResultInvalidArgument</tt>.
70 @date 2015-09-01 If an invalid argument is given to <tt>Send()</tt>, the function now returns <tt>ResultInvalidArgument</tt>.
71 @date 2015-09-01 If there is no audio data to get when <tt>Receive()</tt> is called, the function now returns <tt>ResultNoData</tt>.
72 @date 2015-08-05 Added notes to the <tt>SetVADClampGain()</tt> and <tt>Send()</tt> functions.
73 @date 2015-05-18 Made the <tt>GetVADPower</tt> function public.
74 @date 2015-01-15 Changed the type of the third parameter of the <tt>Receive</tt> function to <tt>nn::pia::StationIndex*</tt>.
75 @date 2014-11-20 Added information about the thread-safe APIs.
76 @date 2014-05-12 Made the <tt>IsClientInConference</tt> function private.
77 @date 2014-05-07 Expanded the <tt>Setting</tt> structure to include a parameter that allows you to configure the maximum number of stations that can participate in a conference chat.
78 @cond CAFE_DOC
79 @date 2014-03-07 Added a new API for using the Automatic Gain Control (AGC) feature.
80 @date 2014-03-07 Added a new API for using the noise suppression feature.
81 @date 2014-03-07 Added a new API for using the echo cancellation feature.
82 @date 2014-03-07 Added a new <tt>Send</tt> function (with different arguments from the previous one).
83 @endcond
84 @date 2014-02-26 Changed the specifications so that the high-pass filter is enabled by default.
85 @date 2014-02-25 Corrected an incorrect default value in the description of the <tt>SetVADActiveGain</tt> function.
86 @date 2014-01-30 Specifying 2-bit ADPCM as the sound codec for main packets is no longer supported.
87 @date 2014-01-30 Quality alert-related API functions have been made private.
88 @date 2014-01-23 Changed the specifications so that the <tt>SetVADClampGain</tt> function returns <tt>nn::Result</tt>.
89 @date 2014-01-23 Changed the specifications so that the <tt> SetQualityAlertThresholdRate</tt> function returns <tt>nn::Result</tt>.
90 @date 2014-01-23 Changed the specifications so that calling the <tt>SetAudioFrameLength</tt> function in a state where communication is not occurring results in <tt>ResultInvalidState</tt> being returned.
91 @date 2014-01-22 Added the <tt>IsInCommunication</tt> member function to determine whether communication is taking place.
92 @date 2014-01-22 Changed the specifications so that the <tt>SetCodec</tt> function returns <tt>ResultInvalidState</tt> when in a state where communication is not occurring.
93 @date 2013-10-02 Added a member function to set the number of receive buffers for <tt>UnreliableProtocol</tt> to the <tt>Setting</tt> structure.
94 @date 2013-10-02 Stopped using <tt>ReliableProtocol</tt> internally.
95 @date 2013-07-12 Defined various constants and enumerations.
96 @date 2013-07-12 Ported set and get functions for various parameters.
97 @date 2013-06-18 Initial version.
98 */
100 {
101 public:
102  static const u32 AUDIO_FRAME_LENGTH_MIN = 64; //!< Specifies the minimum audio frame length (in milliseconds).
103  static const u32 AUDIO_FRAME_LENGTH_MAX = 192; //!< Specifies the maximum audio frame length (in milliseconds).
104  static const u32 AUDIO_FRAME_LENGTH_DEFAULT = 144; //!< Specifies the default audio frame length (in milliseconds).
105 
106  static const size_t AUDIO_DATA_SIZE_PER_MILLI_SEC = 16; //!< Specifies the data size per millisecond (in bytes).
107  static const size_t AUDIO_DATA_SIZE_MIN = (AUDIO_FRAME_LENGTH_MIN * AUDIO_DATA_SIZE_PER_MILLI_SEC); //!< Specifies the minimum audio data size.
108  static const size_t AUDIO_DATA_SIZE_MAX = (AUDIO_FRAME_LENGTH_MAX * AUDIO_DATA_SIZE_PER_MILLI_SEC); //!< Specifies the maximum audio data size.
109  static const size_t AUDIO_DATA_SIZE_DEFAULT = (AUDIO_FRAME_LENGTH_DEFAULT * AUDIO_DATA_SIZE_PER_MILLI_SEC); //!< Specifies the default audio data size.
110 
111  static const size_t MAX_CONFERENCE_CLIENT = 16;
112  static const size_t MAX_AUDIO_STREAM = MAX_CONFERENCE_CLIENT - 1;
113 
114  static const u32 VAD_CLAMP_GAIN_MAX = 0x3fffffff;
115 
116 #if NN_PIA_HF_LIBRARY
117  static const s32 AGC_LEVEL_MIN = 0; //!< The smallest value that can be specified for the AGC level.
118  static const s32 AGC_LEVEL_MAX = 4; //!< The largest value that can be specified for the AGC level.
119  static const s32 AGC_LEVEL_DEFAULT = 1; //!< The default value for the AGC level.
120 
121  static const s32 NOISE_SUPPRESSOR_LEVEL_MIN = 0; //!< The smallest value that can be specified for the noise suppression level.
122  static const s32 NOISE_SUPPRESSOR_LEVEL_MAX = 2; //!< The largest value that can be specified for the noise suppression level.
123  static const s32 NOISE_SUPPRESSOR_LEVEL_DEFAULT = 1; //!< The default value for the noise suppression level (recommended).
124 
125  static const EcMode ECHO_CANCELLER_MODE_DEFAULT = EC_STANDARD; //!< The default value for the echo cancellation mode (recommended).
126 #endif // end of NN_PIA_HF_LIBRARY
127 
128 /*!
129 @brief Stores parameters used by the <tt>Initialize</tt> function.
130 
131 @details This structure contains the various settings for <tt>VoiceProtocol</tt>.
132 @see Initialize()
133 */
134  struct Setting
135  {
136 /*!
137 @brief Instantiates the object with default parameters (default constructor). Each member variable is set to the default value.
138 */
139  Setting(void)
140  : codec(CODEC_4BIT_ADPCM),
141  frameLength(AUDIO_FRAME_LENGTH_DEFAULT),
142  port(10),
143  recvBufNum(32),
144  maxStationNum(MAX_CONFERENCE_CLIENT)
145  {
146  }
147 
148  Codec codec; //!< Specifies the audio codec.
149  size_t frameLength; //!< Specifies the audio frame length. The value is in milliseconds.
150  u16 port; //!< Specifies the port number assigned to the <tt>UnreliableProtocol</tt> object used internally by <tt>PiaChat</tt>. Make sure this does not conflict with the port number used by the application.
151  size_t recvBufNum; //!< Specifies the number of receive buffers for the <tt>UnreliableProtocol</tt> object used internally by <tt>PiaChat</tt>.
152  size_t maxStationNum; //!< The maximum number of stations that can participate in a conference chat.
153  };
154 
155 
156 /*!
157 @cond PRIVATE
158 @brief Instantiates the object with default parameters (default constructor).
159 
160 @details Do not call this constructor directly from applications.
161 Use the <tt>@ref Transport::CreateProtocol</tt> function to create an instance.
162 */
163  VoiceProtocol(void);
164  //! @endcond
165 
166 
167 /*!
168 @cond PRIVATE
169 @brief Destructor.
170 
171 @details Do not call this destructor directly from applications.
172 Use the <tt>@ref Transport::DestroyProtocol</tt> function to destroy an instance.
173 */
174  virtual ~VoiceProtocol(void);
175  //! @endcond
176 
177 
178 /*!
179 @cond PRIVATE
180 @brief This is a dispatch function.
181 
182 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
183 @retval ResultInvalidState Indicates that the <tt>VoiceProtocol::Initialize</tt> function may not have been called. Programming error. Fix your program so that this error is not returned.
184 */
185  virtual nn::Result Dispatch(void);
186  //! @endcond
187 
188 
189 /*!
190 @cond PRIVATE
191 */
192  virtual nn::Result UpdateProtocolEvent(const transport::ProtocolEvent& event);
193  //! @endcond
194 
195 
196  PIA_PROTOCOL_TYPE_INFO(transport::PROTOCOL_TYPE_VOICE);
197 
198 
199 /*!
200 @brief Initializes the instance.
201 
202 @details Call between the <tt>BeginSetup</tt> and <tt>EndSetup</tt> functions.
203 @param[in] setting Specifies a settings parameter structure for <tt>VoiceProtocol</tt>.
204 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds. You must make sure that the implementation of this function in your application does not return any errors.
205 @retval ResultNotInitialized Indicates that the <tt>chat</tt> module is not initialized. Programming error. Fix your program so that this error is not returned.
206 @retval ResultAllocationFailed Indicates that the function failed to allocate memory. Consider providing more memory when calling the <tt>common::Initialize</tt> function. Programming error. Fix your program so that this error is not returned.
207 @retval ResultAlreadyInitialized Indicates that the <tt>VoiceProtocol</tt> instance is already initialized. Programming error. Fix your program so that this error is not returned.
208 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
209 @retval ResultInvalidState Indicates that the function was not called between the <tt>BeginSetup</tt> and <tt>EndSetup</tt> functions. Programming error. Fix your program so that this error is not returned.
210 @see Finalize
211 */
212  nn::Result Initialize(const VoiceProtocol::Setting& setting);
213 
214 
215 /*!
216 @brief Finalizes the instance.
217 
218 @details This function returns without doing anything if it is called before the <tt>Initialize</tt> function has been called.
219 @see Initialize
220 */
221  void Finalize(void);
222 
223 
224 /*!
225 @cond PRIVATE
226 @brief Starts communication.
227 
228 @param[in] myStationIndex Specifies the local <tt>StationIndex</tt>.
229 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
230 @retval ResultInvalidArgument Indicates that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
231 @retval ResultInvalidState Indicates that the <tt>Startup</tt> function has already been called. Programming error. Fix your program so that this error is not returned.
232 */
233  virtual nn::Result Startup(StationIndex myStationIndex);
234  //! @endcond
235 
236 
237 /*!
238 @cond PRIVATE
239 @brief Ends communication.
240 */
241  virtual void Cleanup(void);
242  //! @endcond
243 
244 
245 /*!
246 @brief Determines whether the system is in a communication state.
247 
248 @details This API function is thread-safe.
249 
250 @return Returns <tt>true</tt> if the system is in a communication state or <tt>false</tt> otherwise.
251 */
252  bool IsInCommunication(void) const;
253 
254 
255 /*!
256 @brief Packs audio data in the send queue.
257 
258 @cond CAFE_DOC
259 @details If you use this API to send audio data, you cannot use the AGC, noise suppression, or echo cancellation features.
260 To use these features, use the <tt>@ref Send(const s16*, size_t, const s16*, const s16*)</tt> API function rather than this one.
261 @endcond
262 
263 @details This API function can also be called from threads other than the one that calls the <tt>common::Scheduler::Dispatch()</tt> function.
264 
265 @details The assumption is that this API will receive audio data actually picked up by the microphone.
266 You must be careful when passing synthesized audio data. For more information, see the <tt>SetVADClampGain()</tt> function.
267 
268 @param[in] pAudioBuf Specifies a pointer to the start of the audio data.
269 @param[in] samples Specifies the sampling rate of the audio data.
270 
271 @cond CTR_DOC
272 @param[in] micOffset Specifies the offset (number of samples) between the latest mic sample and last sample of the input mic data.
273 @endcond
274 
275 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
276 @retval ResultInvalidState Indicates that the function was called at the wrong time. Programming error. Fix your program so that this error is not returned.
277 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
278 @cond CAFE_DOC
279 @see Receive, Send(const s16*, size_t, const s16*, const s16*)
280 @endcond
281 @cond CTR_DOC
282 @see Receive
283 @endcond
284 
285 */
286 #if NN_PIA_CTR
287  nn::Result Send(const void* pAudioBuf, u32 samples, u32 micOffset);
288 #elif NN_PIA_CAFE
289  nn::Result Send(const void* pAudioBuf, u32 samples);
290 #else
291 #error "Invalid platform."
292 #endif
293 
294 
295 /*!
296 @brief Extracts audio data from the receive buffer.
297 
298 @details This function also acts internally to mix the audio if it is playing on more than one channel.
299 The audio data written to <tt><var>pAudioBuf</var></tt> is in 16-bit/8 kHz format.
300 This buffer must be aligned to a 32-byte boundary.
301 @details This API can also be called from threads other than the one that calls the <tt>common::Scheduler::Dispatch()</tt> function.
302 
303 @param[out] pAudioBuf Specifies a pointer to the audio data buffer.
304 @param[in] frameDataSize Specifies the size of the audio data buffer.
305 @param[out] pStationIndexArray Stores the <tt>StationIndex</tt> array of the client that sent this stream. Specify <tt>NULL</tt> if this is unnecessary.
306 The number of elements in the array must not exceed the <tt>maxStationNum</tt> member of the <tt>Setting</tt> structure passed when the <tt>Initialize</tt> function was called.
307 
308 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
309 @retval ResultInvalidArgument Indicates that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
310 @retval ResultInvalidState Indicates that the function was called at the wrong time. Programming error. Fix your program so that this error is not returned.
311 @retval ResultNoData There was no audio data to get. Handle appropriately in the application.
312 @cond CAFE_DOC
313 @see Send, Send(const s16*, size_t, const s16*, const s16*)
314 @endcond
315 @cond CTR_DOC
316 @see Send
317 @endcond
318 
319 */
320  nn::Result Receive(void* pAudioBuf, u32 frameDataSize, StationIndex* pStationIndexArray);
321 
322 
323 /*!
324 @brief Adds a client to the conference.
325 
326 @details The local <tt>StationId</tt> does not need to be specified.
327 To start a conference, this function must be called by all parties for each other.
328 For example, if three systems with a <tt>StationId</tt> of 1, 2, and 3 are starting a conference, system 1 must add 2 and 3, system 2 must add 1 and 3, and system 3 must add 1 and 2.
329 If N is the maximum number of people who can connect in a conference, the maximum number of clients that the local system can add to a conference is N-1.
330 This function returns an error if called while not in conference mode.
331 
332 @param[in] id Specifies the <tt>StationId</tt> of the client to add.
333 
334 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
335 @retval ResultInvalidArgument Indicates that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
336 @retval ResultInvalidState Indicates that this function is not in a callable state. Either preparations have not been made for the call, or the maximum number of participating clients has been reached. Programming error. Fix your program so that this error is not returned.
337 
338 
339 */
340  nn::Result AddConferenceClient(StationId id);
341 
342 
343 /*!
344 @cond PRIVATE
345 @brief Adds a client to the conference.
346 */
347  nn::Result AddConferenceClient(StationIndex idx);
348  //! @endcond
349 
350 
351 /*!
352 @brief Removes a client from the conference.
353 
354 @details Have all participants in the conference call this function, and not just the one that is leaving.
355 
356 @param[in] id Specifies the <tt>StationId</tt> of the client to remove.
357 
358 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if execution succeeds.
359 @retval ResultNotFound The client with the specified ID cannot be found. Handle appropriately in the application.
360 @retval ResultInvalidArgument Indicates that one or more arguments are invalid. Programming error. Fix your program so that this error is not returned.
361 @retval ResultInvalidState Indicates that the function was called at the wrong time. Programming error. Fix your program so that this error is not returned.
362 
363 */
364  nn::Result RemoveConferenceClient(StationId id);
365 
366 
367 /*!
368 @cond PRIVATE
369 @brief Removes a client from the conference.
370 */
371  nn::Result RemoveConferenceClient(StationIndex id);
372  //! @endcond
373 
374 
375 /*!
376 @brief Determines whether a client exists in a conference.
377 
378 @param[in] id Specifies the <tt>StationId</tt> of the client to search for.
379 
380 @return Returns <tt>true</tt> if the client is in the conference or <tt>false</tt> otherwise.
381 */
382  bool IsClientInConference(StationId id) const;
383 
384 
385 /*!
386 @cond PRIVATE
387 @brief Determines whether a client exists in a conference.
388 */
389  bool IsClientInConference(StationIndex idx) const;
390  //! @endcond
391 
392 
393 /*!
394 @brief Clears the audio streaming.
395 */
396  void ClearStreaming(void);
397 
398 
399 /*!
400 @brief Sets the audio codec.
401 
402 @details The codec can be changed even while streaming.
403 You can specify 4-bit ADPCM or 2-bit ADPCM, but 2-bit ADPCM is not supported.
404 This function returns <tt>ResultInvalidArgument</tt> if an unsupported audio codec is specified.
405 
406 @param[in] codec The changed audio codec type for the sender.
407 
408 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
409 @retval ResultInvalidArgument Indicates that an argument is invalid. An unsupported codec may have been specified. Programming error. Fix your program so that this error is not returned.
410 @retval ResultInvalidState Indicates that the function was called at the wrong time. Communication might not have been started. Programming error. Fix your program so that this error is not returned.
411 */
412  nn::Result SetCodec(enum Codec codec);
413 
414 
415 /*!
416 @brief Gets the currently configured audio codec.
417 
418 @return Returns the currently configured audio codec for main packets.
419 */
420  enum Codec GetCodec(void) const;
421 
422 
423 /*!
424 @brief Sets the audio frame length.
425 
426 @details For <tt><var>frameLength</var></tt>, you must specify a value between <tt>@ref AUDIO_FRAME_LENGTH_MIN</tt> and <tt>@ref AUDIO_FRAME_LENGTH_MAX</tt> that is also an integer multiple of 8.
427 
428 @param[in] frameLength Specifies the length of the audio frame (in milliseconds).
429 
430 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
431 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
432 @retval ResultInvalidState Indicates that the function was called at the wrong time. Programming error. Fix your program so that this error is not returned.
433 
434 */
435  nn::Result SetAudioFrameLength(u32 frameLength);
436 
437 
438 /*!
439 @brief Gets the currently configured audio frame length.
440 
441 @details If you call this function before initialization, the recommended value <tt>@ref AUDIO_FRAME_LENGTH_DEFAULT</tt> is returned.
442 @details This API function is thread-safe.
443 
444 @return Returns either the value that was set in the <tt><var>frameLength</var></tt> member variable of the <tt>@ref Setting</tt> structure at the time of initialization, or the value set using the <tt>@ref SetAudioFrameLength</tt> function after initialization.
445 */
446  u32 GetAudioFrameLength(void) const;
447 
448 
449 /*!
450 @brief Gets the packet size of audio data.
451 
452 @details This function returns the data size calculated based on the currently configured audio frame length.
453 You can get the currently configured audio frame length by using the <tt>@ref GetAudioFrameLength</tt> function.
454 If called prior to initialization, <tt>@ref AUDIO_DATA_SIZE_DEFAULT</tt>, which corresponds to the recommended audio frame length value in <tt>@ref AUDIO_FRAME_LENGTH_DEFAULT</tt>, is returned.
455 @details This API function is thread-safe.
456 
457 @return Returns the packet size of audio data.
458 
459 
460 */
461  size_t GetAudioDataSize(void) const;
462 
463 
464 /*!
465 @cond PRIVATE
466 @brief Gets the calculated audio scale (square of the average power) of the input audio data.
467 
468 @details The <tt><var>length</var></tt> argument specifies the number of bytes of audio data to input.
469 The audio data must have been sampled at 16-bits/8 kHz.
470 
471 @param[in] audio Specifies the audio data.
472 @param[in] length Specifies the number of bytes of the audio data.
473 
474 @return Returns the audio scale.
475 */
476  u32 GetAudioScale(const void* audio, u32 length);
477  //! @endcond
478 
479 
480 /*!
481 @brief Gets the audio streaming information of the remote station specified by <tt>StationId</tt>.
482 
483 @param[in] id Specifies the <tt>StationId</tt> of the remote station from which to get the audio streaming information.
484 @param[out] pInfo Specifies a pointer to a <tt>@ref AudioInfo</tt> structure.
485 
486 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if execution succeeds.
487 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
488 */
489  nn::Result GetAudioInfo(StationId id, AudioInfo* pInfo) const;
490 
491 
492 /*!
493 @cond PRIVATE
494 @brief Gets the audio streaming information of the other party specified by <tt>StationIndex</tt>.
495 */
496  nn::Result GetAudioInfo(StationIndex idx, AudioInfo* pInfo) const;
497  //! @endcond
498 
499 
500 /*!
501 @brief Sets the time period not to send audio for <tt>@ref SignalNoiseSkip</tt>.
502 
503 @param[in] msec Specifies the time period not to send audio. The value is in milliseconds.
504 @see SignalNoiseSkip, GetNoiseSkipTime
505 */
506  void SetNoiseSkipTime(u32 msec);
507 
508 
509 /*!
510 @brief Gets the time period not to send audio for <tt>@ref SignalNoiseSkip</tt>.
511 
512 @return Returns the time period not to send audio. The value is in milliseconds.
513 @see SignalNoiseSkip, SetNoiseSkipTime
514 */
515  u32 GetNoiseSkipTime(void) const;
516 
517 
518 /*!
519 @brief Stops VAD (Voice Activity Detection) from becoming active and sending audio on the sound of button presses when VAD is enabled but not active.
520 
521 @details Setting up this function enables you to prevent the VAD feature from activating and sending audio on the sound of button presses when VAD is enabled but not active.
522 By not sending audio for a certain time period after button presses, you can minimize the button pressing sounds received by other players.
523 When VAD is active and audio is being sent, the sound of button presses cannot be removed.
524 Specify the time period not to send audio using the <tt>@ref SetNoiseSkipTime</tt> function.
525 @see SetNoiseSkipTime, GetNoiseSkipTime
526 
527 */
528  void SignalNoiseSkip(void);
529 
530 
531 /*!
532 @cond PRIVATE
533 @brief This function enables and disables the spare packet feature.
534 
535 @details The spare packet feature is enabled by default.
536 @param[in] enable Specify <tt>true</tt> to enable or <tt>false</tt> to disable.
537 */
538  void EnableSparePacket(bool enable);
539  //! @endcond
540 
541 
542 /*!
543 @cond PRIVATE
544 @brief Gets whether the spare packet feature is enabled.
545 
546 @details The spare packet feature is enabled by default.
547 @retval true Indicates that the spare packet feature is enabled.
548 @retval false Indicates that the spare packet feature is disabled.
549 */
550  bool IsEnableSparePacket(void) const;
551  //! @endcond
552 
553 
554 /*!
555 @cond PRIVATE
556 @brief Sets the audio codec for spare packets.
557 
558 @details By default, spare packets use the 2-bit ADPCM codec.
559 Use the <tt>@ref SetCodec</tt> function to change the codec for main packets.
560 <b>Note:</b> The only supported codec type for spare packets is 2-bit ADPCM.
561 Accordingly, this function does not need to be called at this time.
562 This function returns <tt>ResultInvalidArgument</tt> if an unsupported codec is specified.
563 @param[in] codec Specifies the codec type for spare packets.
564 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
565 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
566 */
567  nn::Result SetSpareCodec(enum Codec codec);
568  //! @endcond
569 
570 
571 /*!
572 @cond PRIVATE
573 @brief Gets the currently configured audio codec for spare packets.
574 
575 @details This value is meaningless if the spare packet feature is not used.
576 <b>Note:</b> The only supported codec type for spare packets is 2-bit ADPCM.
577 Accordingly, the value returned by this function will always be <tt>@ref CODEC_2BIT_ADPCM</tt> at this time.
578 @return Returns the currently configured codec type for spare packets.
579 */
580  enum Codec GetSpareCodec(void) const;
581  //! @endcond
582 
583 
584 /*!
585 @cond PRIVATE
586 @brief Enables or disables the quality alert feature.
587 
588 @details By default, quality alert is enabled.
589 When this feature is enabled, if the incoming audio packets sent from a peer are often late in arriving, a quality alert flag is set in the outgoing packets to that peer to notify them of the situation.
590 @param[in] enable Specify <tt>true</tt> to enable or <tt>false</tt> to disable.
591 
592 
593 */
594  void EnableQualityAlert(bool enable);
595  //! @endcond
596 
597 
598 /*!
599 @cond PRIVATE
600 @brief Gets whether the quality feature is enabled.
601 
602 @retval true Indicates that the quality alert feature is enabled.
603 @retval false Indicates that the quality alert feature is disabled.
604 */
605  bool IsEnableQualityAlert(void) const;
606  //! @endcond
607 
608 
609 /*!
610 @cond PRIVATE
611 @brief Gets the state of the quality alert flag for the specified <tt>StationIndex</tt>.
612 
613 @details If the return value is <tt>true</tt>, packets received from that peer are often late in arriving.
614 You can find out the state of the local quality alert flag by specifying the local <tt>StationIndex</tt>.
615 @param[in] id Specifies the <tt>StationIndex</tt> of the peer.
616 @retval true Indicates that the quality alert feature is enabled.
617 @retval false Indicates that the quality alert feature is disabled.
618 
619 */
620  bool GetQualityAlert(StationIndex id) const;
621  //! @endcond
622 
623 
624 /*!
625 @cond PRIVATE
626 @brief Sets the package delay threshold at which the quality alert flag is set.
627 
628 @details The value is set as a percentage. It is set to 20% by default.
629 @param[in] rate Specifies the packet delay threshold (%).
630 
631 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if execution succeeds.
632 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
633 
634 @see GetQualityAlertThresholdRate
635 */
636  nn::Result SetQualityAlertThresholdRate(u8 rate);
637  //! @endcond
638 
639 
640 /*!
641 @cond PRIVATE
642 @brief Gets the configured package delay threshold at which the quality alert flag is set.
643 
644 @return Returns the packet delay threshold, in percent (%).
645 @see SetQualityAlertThresholdRate
646 */
647  u8 GetQualityAlertThresholdRate(void) const;
648  //! @endcond
649 
650 
651 /*!
652 @cond PRIVATE
653 @brief Sets the duration for keeping the quality alert flag set.
654 
655 @details Sets the duration in seconds for the local station to keep its quality alert flag set after receiving a quality alert notification flag from a peer.
656 The default value is 1800 seconds.
657 @param[in] sec Specifies the duration of the flag (in seconds).
658 @see GetQualityAlertDuration
659 */
660  void SetQualityAlertDuration(u32 sec);
661  //! @endcond
662 
663 
664 /*!
665 @cond PRIVATE
666 @brief Gets the duration for keeping the quality alert flag set.
667 
668 @details Gets the duration in seconds for the local station to keep its quality alert flag set after receiving a quality alert notification flag from a peer.
669 @return Returns the duration of the flag (in seconds).
670 @see SetQualityAlertDuration
671 
672 */
673  u32 GetQualityAlertDuration(void) const;
674  //! @endcond
675 
676 
677 /*!
678 @cond PRIVATE
679 @brief Sets the number of nearby packets to sample when measuring the packet delay.
680 
681 @details This function sets the number of nearby packets to sample when measuring the packet delay.
682 A larger value increases accuracy, but also reduces responsiveness to changes in connection quality.
683 The default value is 40 packets.
684 @param[in] num Specifies the number of nearby packets to sample.
685 @see GetQualityAlertSamplingPacketNum
686 */
687  void SetQualityAlertSamplingPacketNum(u16 num);
688  //! @endcond
689 
690 
691 /*!
692 @cond PRIVATE
693 @brief Gets the number of nearby packets to sample when measuring the packet delay.
694 
695 @return Returns the number of nearby packets to sample.
696 @see SetQualityAlertSamplingPacketNum
697 */
698  u16 GetQualityAlertSamplingPacketNum(void) const;
699  //! @endcond
700 
701 
702 /*!
703 @cond PRIVATE
704 @brief Enables or disables the drop recover feature.
705 
706 @details The drop recover feature is enabled by default.
707 When the drop recover feature is enabled and packet loss occurs, the audio data in the lost packets is recovered.
708 When the spare packet feature is enabled and the spare packet of the subsequent packet can be used, the audio data in the current packet can be restored based on the audio data in the spare packet, improving audio quality.
709 @param[in] flag Specify <tt>true</tt> to enable or <tt>false</tt> to disable.
710 
711 
712 */
713  void EnableDropRecover(bool enable);
714  //! @endcond
715 
716 
717 /*!
718 @cond PRIVATE
719 @brief Gets whether the drop recover feature is enabled.
720 
721 @retval true Indicates that the drop recover feature is enabled.
722 @retval false Indicates that the drop recover feature is disabled.
723 */
724  bool IsEnableDropRecover(void) const;
725  //! @endcond
726 
727 
728 /*!
729 @cond PRIVATE
730 @brief Enables or disables the VAD (Voice Activity Detection) feature.
731 
732 @details The VAD feature is enabled by default.
733 When VAD is enabled, in addition to evaluating audio inside the <tt>@ref Dispatch</tt> function, decisions are also made automatically about whether to send packets.
734 @param[in] flag Specify <tt>true</tt> to enable or <tt>false</tt> to disable.
735 
736 */
737  void EnableVAD(bool enable);
738  //! @endcond
739 
740 
741 /*!
742 @cond PRIVATE
743 @brief Gets whether the VAD (Voice Activity Detection) feature is enabled or disabled.
744 
745 @retval true Indicates that the VAD feature is enabled.
746 @retval false Indicates that the VAD feature is disabled.
747 */
748  bool IsEnableVAD(void) const;
749  //! @endcond
750 
751 
752 /*!
753 @brief Gets whether audio is detected using the VAD (Voice Activity Detection) algorithm.
754 
755 @details Returns <tt>true</tt> while frames with audio (speech frames) are present, or <tt>false</tt> while the frames without audio (silent frames) are present.
756 When the VAD feature is disabled, this function always returns <tt>false</tt> regardless of whether there is any voice activity.
757 
758 @return Returns <tt>true</tt> if it is determined that audio is present or <tt>false</tt> otherwise.
759 
760 */
761  bool GetVADActivity(void) const;
762 
763 
764 /*!
765 @brief Gets the average power of audio data in the current audio frame.
766 
767 @details The VAD algorithm detects audio based on the size of this value.
768 This value is equivalent to the average power of the audio data (the square root of the volume scale of the audio data used in the <tt>GetAudioScale</tt> function or <tt>@ref SetVADClampGain</tt> function) divided by a normalization factor (<tt>256</tt>).
769 @return Returns the average power of the audio data in the current audio frame.
770 
771 
772 */
773  u16 GetVADPower(void) const;
774 
775 
776 /*!
777 @cond PRIVATE
778 @brief Resets the internal state of VAD (Voice Activity Detection).
779 
780 @details Call this function after making changes to the microphone gain or similar settings.
781 */
782  void ResetVAD(void);
783  //! @endcond
784 
785 
786 /*!
787 @brief Sets the speech frame detection threshold.
788 
789 @details When the previous audio frame is recognized as a silent frame, this threshold value is used to determine whether the current audio frame includes audio.
790 A frame is recognized as a speech frame when the following conditions are met: <tt>Ts</tt> is the threshold value, <tt>Ec</tt> is the average speech power of the audio data in the current frame, and <tt>En</tt> is the average speech power of the audio data in the four frames immediately prior to the current one. The difference between <tt>Ec</tt> and <tt>En</tt> are compared. <br>
791 Ec > En * Ts / 100<br />
792 The <tt><var>value</var></tt> parameter takes the <tt>Ts</tt> value. The default value is 350.
793 In this case, the threshold of the power difference between <tt>En</tt> and <tt>Ec</tt> is equivalent to <tt>20 * log (350 / 100) = 10.9 dB</tt>.
794 @param[in] value Specifies the speech frame detection threshold.
795 @see GetVADActiveGain
796 
797 
798 
799 */
800  void SetVADActiveGain(u16 value);
801 
802 
803 /*!
804 @brief Gets the current speech frame detection threshold.
805 
806 @return Returns the speech frame detection threshold.
807 @see SetVADActiveGain
808 */
809  u16 GetVADActiveGain(void) const;
810 
811 
812 /*!
813 @brief Sets the silent frame detection threshold.
814 
815 @details When the previous audio frame is recognized as a speech frame, this threshold value is used to determine whether the current audio frame is silent.
816 A frame is recognized as silent when the following condition is met, where <tt>Tn</tt> is the threshold value, <tt>Ec</tt> is the average speech power of the audio data in the nearest four frames, and <tt>En</tt> is the average speech power of the audio data in the four frames before the last frame to be deemed a silent frame. <br>
817 Ec < En * Tn / 100<br />
818 However, the sending of audio frames is not actually stopped until the consecutive number of frames deemed silent reaches the value specified with the <tt>@ref SetVADReleaseTime</tt> function.
819 The <tt><var>value</var></tt> parameter takes the <tt>Tn</tt> value. The default value is 280.
820 In this case, the threshold of the power difference between <tt>En</tt> and <tt>Ec</tt> is equivalent to <tt>20 * log (280 / 100) = 8.94 dB</tt>.
821 @param[in] value Specifies the silent frame detection threshold.
822 @see GetVADInactiveGain
823 
824 
825 
826 
827 */
828  void SetVADInactiveGain(u16 value);
829 
830 
831 /*!
832 @brief Gets the current silent frame detection threshold.
833 
834 @return Returns the silent frame detection threshold.
835 @see SetVADInactiveGain
836 */
837  u16 GetVADInactiveGain(void) const;
838 
839 
840 /*!
841 @brief Sets the time in number of packets before the sending of packets stops after detecting silence.
842 
843 @details To prevent VAD from detecting silence in the middle of a conversation because, for example, the user takes a breath, set the release time to at least 500 ms.
844 Set the parameter to the time to wait in number of packets before actually stopping the sending of packets after silence is detected.
845 The default is 5 packets (<tt>144 * 5 = 720 ms</tt>).
846 @param[in] packetNum Specifies the release time (in number of packets).
847 @see GetVADReleaseTime
848 
849 */
850  void SetVADReleaseTime(u32 packetNum);
851 
852 
853 /*!
854 @brief Gets the time in number of packets before the sending of packets stops after detecting silence.
855 
856 @return Returns the release time (in number of packets).
857 @see SetVADReleaseTime
858 */
859  u32 GetVADReleaseTime(void) const;
860 
861 
862 /*!
863 @brief Sets the volume threshold as a volume scale value (the square of the average power) for unconditionally determining silence.
864 
865 @details <tt><var>value</var></tt> takes a volume scale value in the range from <tt>0</tt> through <tt>0x3FFFFFFF</tt>, and any audio frame with a volume scale set below this threshold is treated as silence.
866 
867 The volume scale of the audio data as obtained by the <tt>GetAudioScale</tt> function is used for this value. The default value is 49.
868 
869 @details Audio frames with volumes below the value set by this API are treated as silence by the library and the VAD status is not updated.
870 For this reason, if you want to pass synthesized audio data to a function that sends audio data, you must make sure its volume is higher than the threshold set by this function.
871 Operations could be impaired if data at very low volume below this threshold (for example, data to fill the memory with zeros) continues to be passed to a function that sends audio data.
872 
873 @param[in] value Specifies the volume threshold at which a frame is unconditionally determined to be silent.
874 
875 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess()</tt> function returns <tt>true</tt> if execution succeeds.
876 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
877 
878 @see GetVADClampGain
879 
880 
881 
882 
883 */
884  nn::Result SetVADClampGain(u32 value);
885 
886 
887 /*!
888 @brief Gets the volume threshold as a volume scale value for unconditionally determining silence.
889 
890 @details The volume scale value is specified in the range from <tt>0</tt> through <tt>0x3FFFFFFF</tt>.
891 @return Returns the volume threshold at which a frame is unconditionally determined to be silent.
892 @see SetVADClampGain
893 */
894  u32 GetVADClampGain(void) const;
895 
896 
897 /*!
898 @cond PRIVATE
899 @brief Enables or disables the high-pass filter.
900 
901 @details By default, the high-pass filter is enabled.
902 When this feature is enabled, the high-pass filter is applied to the audio being sent inside the <tt>@ref Dispatch</tt> function to eliminate low-range noise of the audio data.
903 @param[in] enable Specify <tt>true</tt> to enable or <tt>false</tt> to disable.
904 
905 
906 */
907  void EnableHPF(bool enable);
908  //! @endcond
909 
910 
911 /*!
912 @cond PRIVATE
913 @brief Gets whether the high-pass filter is enabled.
914 
915 @retval true Indicates that the high-pass filter is enabled.
916 @retval false Indicates that the high-pass filter is disabled.
917 */
918  bool IsEnableHPF(void) const;
919 //! @endcond
920 
921 
922 #if NN_PIA_HF_LIBRARY
923 /*!
924 @brief Uses the echo cancellation, AGC, and noise suppression features when sending audio.
925 
926 @details This API uses approximately 16 KB of the stack. Make sure that you allocate a stack of adequate size for the thread that calls this API.
927 @details This API blocks for about 14 to 20 milliseconds. It blocks because it runs internal audio signal processes related to echo cancellation, AGC, and noise suppression.
928 @details This API can also be called from threads other than the one that calls the <tt>common::Scheduler::Dispatch()</tt> function.
929 @details The assumption is that this API will receive audio data actually picked up by the microphone.
930 You must be careful when passing synthesized audio data. For more information, see the <tt>SetVADClampGain()</tt> function.
931 
932 @param[in] pAudioBuf The audio data to send (generally microphone input). The sampling frequency is 8 kHz.
933 @param[in] samples Number of samples. These samples must correspond to the audio data frame length.
934 @param[in] pRefLeftIn Reference data input for the left channel. The sampling frequency is 32 kHz.
935 @param[in] pRefRightIn Reference data input for the right channel. The sampling frequency is 32 kHz.
936 
937 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
938 @retval ResultNotInitialized Indicates that this API was called when the <tt>VoiceProtocol</tt> instance was not in an initialized state. Programming error. Fix your program so that this error is not returned.
939 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
940 @retval ResultInvalidState Indicates that this API function was called at the wrong time. Programming error. Fix your program so that this error is not returned.
941 @see Receive
942 
943 
944 
945 */
946  nn::Result Send(const s16* pAudioBuf, size_t samples, const s16* pRefLeftIn, const s16* pRefRightIn);
947 
948 
949 /*!
950 @brief Enables or disables echo cancellation.
951 @details By default, echo cancellation is enabled.
952 
953 @param[in] bEnable true - Enabled, false - Disabled
954 
955 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
956 @retval ResultNotInitialized Indicates that this API was called when the <tt>VoiceProtocol</tt> instance was not in an initialized state. Programming error. Fix your program so that this error is not returned.
957 @see Send(const s16*, size_t, const s16*, const s16*), IsEnableEchoCanceller, SetEchoCancellerMode, GetEchoCancellerMode
958 */
959  nn::Result EnableEchoCanceller(bool bEnable);
960 
961 
962 /*!
963 @brief Gets whether echo cancellation is enabled or disabled.
964 
965 @return Returns <tt>true</tt> if echo cancellation is enabled, and returns <tt>false</tt> otherwise.
966 @see Send(const s16*, size_t, const s16*, const s16*), EnableEchoCanceller, SetEchoCancellerMode, GetEchoCancellerMode
967 */
968  bool IsEnableEchoCanceller() const;
969 
970 
971 /*!
972 @brief Sets the echo cancellation operation mode.
973 
974 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
975 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
976 @retval ResultNotInitialized Indicates that this API was called when the <tt>VoiceProtocol</tt> instance was not in an initialized state. Programming error. Fix your program so that this error is not returned.
977 @see Send(const s16*, size_t, const s16*, const s16*), EnableEchoCanceller, IsEnableEchoCanceller, GetEchoCancellerMode
978 */
979  nn::Result SetEchoCancellerMode(enum EcMode ecMode);
980 
981 
982 /*!
983 @brief Gets the echo cancellation operation mode.
984 
985 @return Returns the echo cancellation operation mode.
986 @retval EC_VOID Indicates that the echo cancellation operation mode is not in an obtainable state.
987 @see Send(const s16*, size_t, const s16*, const s16*), EnableEchoCanceller, IsEnableEchoCanceller, SetEchoCancellerMode
988 */
989  enum EcMode GetEchoCancellerMode() const;
990 
991 
992 /*!
993 @brief Enables or disables the Automatic Gain Control (AGC) feature.
994 
995 @details By default, the AGC feature is enabled.
996 @param[in] bEnable true - Enabled, false - Disabled
997 
998 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
999 @retval ResultNotInitialized Indicates that this API was called when the <tt>VoiceProtocol</tt> instance was not in an initialized state. Programming error. Fix your program so that this error is not returned.
1000 @see Send(const s16*, size_t, const s16*, const s16*), IsEnableAgc, SetAgcLevel, GetAgcLevel
1001 */
1002  nn::Result EnableAgc(bool bEnable);
1003 
1004 
1005 /*!
1006 @brief Gets whether the Automatic Gain Control (AGC) feature is enabled or disabled.
1007 
1008 @return Returns <tt>true</tt> if the AGC feature is enabled or <tt>false</tt> otherwise.
1009 @see Send(const s16*, size_t, const s16*, const s16*), EnableAgc, SetAgcLevel, GetAgcLevel
1010 */
1011  bool IsEnableAgc() const;
1012 
1013 
1014 /*!
1015 @brief Sets the Automatic Gain Control (AGC) level.
1016 Values of at least <tt>AGC_LEVEL_MIN</tt> and no greater than <tt>AGC_LEVEL_MAX</tt> can be set.
1017 
1018 @details If the argument is set to <tt>AGC_LEVEL_MIN</tt>, AGC is not actually being used because the amplification rate is 1×.
1019 @details The greater the value set, the more the amplification rate increases, but it also becomes easier for feedback to occur. Setting a value of <tt>1</tt> or <tt>2</tt> is recommended.
1020 
1021 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
1022 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
1023 @retval ResultNotInitialized Indicates that this API was called when the <tt>VoiceProtocol</tt> instance was not in an initialized state. Programming error. Fix your program so that this error is not returned.
1024 @see Send(const s16*, size_t, const s16*, const s16*), EnableAgc, IsEnableAgc, GetAgcLevel
1025 */
1026  nn::Result SetAgcLevel(s32 level);
1027 
1028 
1029 /*!
1030 @brief Gets the AGC (Automatic Gain Control) level.
1031 
1032 @return Returns a value of at least <tt>AGC_LEVEL_MIN</tt> but not greater than <tt>AGC_LEVEL_MAX</tt> if successful.
1033 @retval -1 The AGC level is not in a state where it can be obtained.
1034 @see Send(const s16*, size_t, const s16*, const s16*), EnableAgc, IsEnableAgc, SetAgcLevel
1035 */
1036  s32 GetAgcLevel() const;
1037 
1038 
1039 /*!
1040 @brief Enables or disables noise suppression.
1041 @details By default, noise suppression is enabled.
1042 
1043 @param[in] bEnable true - Enabled, false - Disabled
1044 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
1045 @retval ResultNotInitialized Indicates that this API was called when the <tt>VoiceProtocol</tt> instance was not in an initialized state. Programming error. Fix your program so that this error is not returned.
1046 @see Send(const s16*, size_t, const s16*, const s16*), IsEnableNoiseSuppressor, SetNoiseSuppressorLevel, GetNoiseSuppressorLevel
1047 */
1048  nn::Result EnableNoiseSuppressor(bool bEnable);
1049 
1050 
1051 /*!
1052 @brief Gets whether noise suppression is enabled or disabled.
1053 
1054 @return Returns <tt>true</tt> if the noise suppression feature is enabled or <tt>false</tt> otherwise.
1055 @see Send(const s16*, size_t, const s16*, const s16*), EnableNoiseSuppressor, SetNoiseSuppressorLevel, GetNoiseSuppressorLevel
1056 */
1057  bool IsEnableNoiseSuppressor() const;
1058 
1059 /*!
1060 @brief Sets the noise suppression level.
1061 Values of at least <tt>NOISE_SUPPRESSOR_LEVEL_MIN</tt> and no greater than <tt>NOISE_SUPPRESSOR_LEVEL_MAX</tt> can be set.
1062 <tt>NOISE_SUPPRESSOR_LEVEL_DEFAULT</tt> is the recommended value.
1063 
1064 @return Returns a <tt>Result</tt> value for which the <tt>IsSuccess</tt> function returns <tt>true</tt> if execution succeeds.
1065 @retval ResultInvalidArgument Indicates that an argument is invalid. Programming error. Fix your program so that this error is not returned.
1066 @retval ResultNotInitialized Indicates that this API was called when the <tt>VoiceProtocol</tt> instance was not in an initialized state. Programming error. Fix your program so that this error is not returned.
1067 @see Send(const s16*, size_t, const s16*, const s16*), EnableNoiseSuppressor, IsEnableNoiseSuppressor, GetNoiseSuppressorLevel
1068 */
1069  nn::Result SetNoiseSuppressorLevel(s32 level);
1070 
1071 
1072 /*!
1073 @brief Gets the noise suppression level.
1074 
1075 @return Returns a value of at least <tt>NOISE_SUPPRESSOR_LEVEL_MIN</tt> but not greater than <tt>NOISE_SUPPRESSOR_LEVEL_MAX</tt> if successful.
1076 @retval –1 The noise suppression level is not in a state where it can be obtained.
1077 @see Send(const s16*, size_t, const s16*, const s16*), EnableNoiseSuppressor, IsEnableNoiseSuppressor, SetNoiseSuppressorLevel
1078 */
1079  s32 GetNoiseSuppressorLevel() const;
1080 #endif // end of NN_PIA_HF_LIBRARY
1081 
1082 
1083 #if NN_PIA_CTR
1084 /*!
1085 @cond PRIVATE
1086 @brief Enables or disables the biquad filter.
1087 
1088 @details By default, the biquad filter is disabled.
1089 When this feature is enabled, the biquad filter is applied inside the <tt>@ref Dispatch</tt> function to eliminate non-speech noise in the audio being sent.
1090 @param[in] enable Specify <tt>true</tt> to enable or <tt>false</tt> to disable.
1091 
1092 
1093 */
1094  void EnableBPF(bool enable);
1095  //! @endcond
1096 
1097 
1098 /*!
1099 @cond PRIVATE
1100 @brief Gets whether the biquad filter is enabled.
1101 
1102 @retval true Indicates that the biquad filter is enabled.
1103 @retval false Indicates that the biquad filter is disabled.
1104 */
1105  bool IsEnableBPF(void) const;
1106  //! @endcond
1107 
1108 
1109 /*!
1110 @cond PRIVATE
1111 @brief Enables or disables the echo cancellation feature.
1112 
1113 @details The echo cancellation feature is enabled by default.
1114 When the echo cancellation feature is turned on, echo cancellation runs in the <tt>@ref Send</tt> function.
1115 @param[in] flag Specify <tt>true</tt> to enable or <tt>false</tt> to disable.
1116 
1117 */
1118  void EnableEchoCancel(bool enable);
1119  //! @endcond
1120 
1121 
1122 /*!
1123 @cond PRIVATE
1124 @brief Gets whether the echo cancellation feature is enabled.
1125 
1126 @retval true Indicates that the echo cancellation feature is enabled.
1127 @retval false Indicates that the echo cancellation feature is disabled.
1128 */
1129  bool IsEnableEchoCancel(void) const;
1130  //! @endcond
1131 
1132 
1133 /*!
1134 @brief Supplies reference data for echo cancellation.
1135 
1136 @details Call the <tt>nn::snd::GetMixedBusData</tt> function at every sound DSP interrupt (every 5 ms), and pass the 5 ms of 16-bit/32 kHz stereo data obtained by that function to the <tt><var>pBuffer</var></tt> of this function.
1137 This function does nothing if <tt><var>size</var></tt> is not the correct size for 5 milliseconds of 16-bit/32 kHz stereo data.
1138 @param[in] pBuffer Specifies reference data for echo cancellation.
1139 @param[in] size Specifies the size of the reference data for echo cancellation.
1140 
1141 
1142 
1143 */
1144  void HandleReference(const u8* pBuffer, u32 size);
1145 #endif // end of NN_PIA_CTR
1146 
1147 
1148 /*!
1149 @brief Prints information that is useful for debugging.
1150 
1151 @param[in] flag Specifies the bitwise OR of trace flags. For more information, see the <tt>@ref TraceFlag</tt> type.
1152 */
1153  virtual void Trace(u64 flag) const;
1154 
1155 
1156 private:
1157  static const size_t NET_SEND_BUFF_SIZE = 2048;
1158  static const size_t NET_SEND_DATA_MAX = 80;
1159 
1160  struct SendDataStructure
1161  {
1162  u32 sendBuff[NET_SEND_BUFF_SIZE / sizeof(u32)];
1163  nn::nex::ConnectionID destCid;
1164  u32 dataSize;
1165  u32 destCidBmp;
1166  };
1167 
1168  bool allocProc(size_t maxStationNum);
1169  void freeProc(void);
1170  size_t calcAudioBufferSize(size_t maxStationNum) const;
1171 
1172  bool initializeVct(void);
1173  void finalizeVct(void);
1174 
1175  nn::Result setupProtocols(u16 port, size_t recvBufNum);
1176  void destroyProtocols(void);
1177 
1178  void updateSessionEndMonitoringData();
1179 
1180  static bool SendDataCallback(u16 cid, const void* buff, u32 size);
1181  bool SendDataCallbackImpl(u32 cid, const void* pBuff, u32 size);
1182 
1183  static bool SendMultiDataCallback(u32 cidBmp, const void* pBuf, size_t size);
1184  bool SendMultiDataCallbackImpl(u32 cidBmp, const void* pBuf, size_t size);
1185 
1186  s32 getPassedTime() const; // Returns the elapsed time since the <tt>Startup</tt> function was called. The value is in milliseconds.
1187 
1188  nn::Result receiveCore(void* pAudioBuf, u32 frameDataSize, u16* pCidList);
1189 
1190  u32 m_UnreliableHandle;
1191  transport::UnreliableProtocol* m_pUnreliable;
1192 
1193  VCTSession* m_pSession;
1194  u8* m_pAudioBuffer;
1195  SendDataStructure* m_pSendDataInfo;
1196  u32 m_ReqSendDataIndexR;
1197  u32 m_ReqSendDataIndexW;
1198 
1199  StationIndex m_LocalStationIndex;
1200 
1201  Setting m_Setting; // The argument that was passed when calling <tt>Initialize</tt> is copied.
1202 
1203  common::CriticalSection m_SendCs;
1204 
1205  size_t m_DispatchCount; // Specifies the number of times the <tt>Dispatch</tt> function was called.
1206 
1207  u64 m_TotalSendDataSize;
1208  u64 m_TotalReceiveDataSize;
1209  common::Time m_StartupTime;
1210 
1211 #if NN_PIA_HF_LIBRARY
1212  HandsFree* m_pHandsFree;
1213  s16* m_pAudioOutBuf;
1214 #endif
1215 
1216  static VoiceProtocol* s_pVoiceProtocol; // Singleton pointer.
1217 };
1218 }
1219 }
1220 } // end of namespace nn::pia::chat
size_t recvBufNum
Specifies the number of receive buffers for the UnreliableProtocol object used internally by PiaChat...
Definition: chat_VoiceProtocol.h:151
Class that represents time.
Definition: common_Time.h:39
StationIndex
Enumerates StationIndex values.
Definition: platformCtr.h:44
Definition of the StationId identifying the station within the session.
Definition: types.h:33
Definition: assert.h:115
size_t frameLength
Specifies the audio frame length. The value is in milliseconds.
Definition: chat_VoiceProtocol.h:149
virtual void Trace(u64 flag) const
Prints information that is useful for debugging.
Specifies 4-bit IMA-ADPCM.
Definition: chat_types.h:35
void Finalize(void)
Initializes the transport module. This function does nothing and returns if it is called before the I...
u16 port
Specifies the port number assigned to the UnreliableProtocol object used internally by PiaChat...
Definition: chat_VoiceProtocol.h:150
Represents the unreliable protocol class, with which data may be lost. UnreliableProtocol does not gu...
Definition: transport_UnreliableProtocol.h:75
Codec codec
Specifies the audio codec.
Definition: chat_VoiceProtocol.h:148
Specifies standard echo cancellation.
Definition: chat_types.h:45
EcMode
Enumerates the modes of echo cancellation.
Definition: chat_types.h:43
Stores parameters used by the Initialize function.
Definition: chat_VoiceProtocol.h:134
Contains audio streaming information.
Definition: chat_types.h:62
Protocol base class.
Definition: transport_Protocol.h:44
Setting(void)
Instantiates the object with default parameters (default constructor). Each member variable is set to...
Definition: chat_VoiceProtocol.h:139
Codec
Enumerates audio codecs.
Definition: chat_types.h:29
size_t maxStationNum
The maximum number of stations that can participate in a conference chat.
Definition: chat_VoiceProtocol.h:152
Contains member functions that provide voice chat functionality.
Definition: chat_VoiceProtocol.h:99
nn::Result Initialize(void)
Initializes the transport module.