toxcore/toxav/toxav.h

330 lines
10 KiB
C
Raw Normal View History

2014-02-10 06:06:44 +08:00
/** toxav.h
2014-02-17 09:01:30 +08:00
*
2014-02-10 06:06:44 +08:00
* Copyright (C) 2013 Tox project All Rights Reserved.
*
* This file is part of Tox.
*
* Tox is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* Tox is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with Tox. If not, see <http://www.gnu.org/licenses/>.
*
*/
#ifndef __TOXAV
#define __TOXAV
#include <inttypes.h>
2014-06-19 05:52:34 +08:00
#ifdef __cplusplus
extern "C" {
#endif
2014-02-10 06:06:44 +08:00
typedef struct _ToxAv ToxAv;
2014-11-27 05:03:22 +08:00
2014-11-27 05:17:29 +08:00
/* vpx_image_t */
#include <vpx/vpx_image.h>
2014-11-27 05:03:22 +08:00
2014-11-18 07:46:46 +08:00
typedef void ( *ToxAVCallback ) ( void *agent, int32_t call_idx, void *arg );
typedef void ( *ToxAvAudioCallback ) (void *agent, int32_t call_idx, const int16_t *PCM, uint16_t size, void *data);
typedef void ( *ToxAvVideoCallback ) (void *agent, int32_t call_idx, const vpx_image_t *img, void *data);
2014-02-10 06:06:44 +08:00
2015-02-26 09:51:37 +08:00
#ifndef TOX_DEFINED
#define TOX_DEFINED
2014-02-10 06:06:44 +08:00
typedef struct Tox Tox;
#endif
2014-02-16 03:44:33 +08:00
#define RTP_PAYLOAD_SIZE 65535
2014-02-10 06:06:44 +08:00
2014-02-17 09:01:30 +08:00
/**
2014-11-18 07:46:46 +08:00
* Callbacks ids that handle the call states.
2014-02-10 06:06:44 +08:00
*/
typedef enum {
2014-11-18 07:46:46 +08:00
av_OnInvite, /* Incoming call */
av_OnRinging, /* When peer is ready to accept/reject the call */
av_OnStart, /* Call (RTP transmission) started */
av_OnCancel, /* The side that initiated call canceled invite */
av_OnReject, /* The side that was invited rejected the call */
av_OnEnd, /* Call that was active ended */
av_OnRequestTimeout, /* When the requested action didn't get response in specified time */
av_OnPeerTimeout, /* Peer timed out; stop the call */
av_OnPeerCSChange, /* Peer changing Csettings. Prepare for changed AV */
av_OnSelfCSChange /* Csettings change confirmation. Once triggered peer is ready to recv changed AV */
2014-02-10 06:06:44 +08:00
} ToxAvCallbackID;
/**
2014-11-18 07:46:46 +08:00
* Call type identifier.
2014-02-10 06:06:44 +08:00
*/
typedef enum {
2014-11-18 07:46:46 +08:00
av_TypeAudio = 192,
av_TypeVideo
2014-02-10 06:06:44 +08:00
} ToxAvCallType;
2014-07-05 00:16:53 +08:00
typedef enum {
2014-11-26 07:19:57 +08:00
av_CallNonExistent = -1,
2014-07-05 00:16:53 +08:00
av_CallInviting, /* when sending call invite */
av_CallStarting, /* when getting call invite */
av_CallActive,
av_CallHold,
2014-11-26 07:19:57 +08:00
av_CallHungUp
2014-07-05 00:16:53 +08:00
} ToxAvCallState;
2014-02-16 04:29:41 +08:00
/**
2014-11-29 20:42:19 +08:00
* Error indicators. Values under -20 are reserved for toxcore.
2014-02-16 04:29:41 +08:00
*/
2014-02-10 06:06:44 +08:00
typedef enum {
2014-11-18 07:46:46 +08:00
av_ErrorNone = 0,
2014-11-29 20:42:19 +08:00
av_ErrorUnknown = -1, /* Unknown error */
av_ErrorNoCall = -20, /* Trying to perform call action while not in a call */
av_ErrorInvalidState = -21, /* Trying to perform call action while in invalid state*/
av_ErrorAlreadyInCallWithPeer = -22, /* Trying to call peer when already in a call with peer */
av_ErrorReachedCallLimit = -23, /* Cannot handle more calls */
av_ErrorInitializingCodecs = -30, /* Failed creating CSSession */
av_ErrorSettingVideoResolution = -31, /* Error setting resolution */
av_ErrorSettingVideoBitrate = -32, /* Error setting bitrate */
av_ErrorSplittingVideoPayload = -33, /* Error splitting video payload */
av_ErrorEncodingVideo = -34, /* vpx_codec_encode failed */
av_ErrorEncodingAudio = -35, /* opus_encode failed */
av_ErrorSendingPayload = -40, /* Sending lossy packet failed */
av_ErrorCreatingRtpSessions = -41, /* One of the rtp sessions failed to initialize */
av_ErrorNoRtpSession = -50, /* Trying to perform rtp action on invalid session */
av_ErrorInvalidCodecState = -51, /* Codec state not initialized */
av_ErrorPacketTooLarge = -52, /* Split packet exceeds it's limit */
2014-02-10 06:06:44 +08:00
} ToxAvError;
/**
2014-11-18 07:46:46 +08:00
* Locally supported capabilities.
*/
typedef enum {
2014-11-18 07:46:46 +08:00
av_AudioEncoding = 1 << 0,
av_AudioDecoding = 1 << 1,
av_VideoEncoding = 1 << 2,
av_VideoDecoding = 1 << 3
} ToxAvCapabilities;
2014-04-07 05:59:18 +08:00
/**
2014-11-18 07:46:46 +08:00
* Encoding settings.
2014-04-07 05:59:18 +08:00
*/
2014-11-18 07:46:46 +08:00
typedef struct _ToxAvCSettings {
2014-07-27 01:29:49 +08:00
ToxAvCallType call_type;
2014-07-27 09:26:32 +08:00
uint32_t video_bitrate; /* In kbits/s */
uint16_t max_video_width; /* In px */
uint16_t max_video_height; /* In px */
2014-04-07 05:59:18 +08:00
uint32_t audio_bitrate; /* In bits/s */
uint16_t audio_frame_duration; /* In ms */
uint32_t audio_sample_rate; /* In Hz */
uint32_t audio_channels;
2014-07-27 06:26:58 +08:00
} ToxAvCSettings;
2014-04-07 05:59:18 +08:00
2014-07-27 06:26:58 +08:00
extern const ToxAvCSettings av_DefaultSettings;
2014-04-07 05:59:18 +08:00
2014-02-16 04:29:41 +08:00
/**
2014-11-18 07:46:46 +08:00
* Start new A/V session. There can only be one session at the time.
2014-02-16 04:29:41 +08:00
*/
2014-05-17 01:56:40 +08:00
ToxAv *toxav_new(Tox *messenger, int32_t max_calls);
2014-02-16 04:29:41 +08:00
/**
2014-11-18 07:46:46 +08:00
* Remove A/V session.
2014-02-16 04:29:41 +08:00
*/
2014-02-17 09:01:30 +08:00
void toxav_kill(ToxAv *av);
2014-02-10 06:06:44 +08:00
2014-02-16 04:29:41 +08:00
/**
2014-11-18 07:46:46 +08:00
* Returns the interval in milliseconds when the next toxav_do() should be called.
* If no call is active at the moment returns 200.
2014-02-16 04:29:41 +08:00
*/
2014-11-18 07:46:46 +08:00
uint32_t toxav_do_interval(ToxAv *av);
/**
2014-11-18 07:46:46 +08:00
* Main loop for the session. Best called right after tox_do();
*/
2014-11-18 07:46:46 +08:00
void toxav_do(ToxAv *av);
/**
2014-11-18 07:46:46 +08:00
* Register callback for call state.
*/
2014-11-18 07:46:46 +08:00
void toxav_register_callstate_callback (ToxAv *av, ToxAVCallback cb, ToxAvCallbackID id, void *userdata);
2014-02-10 06:06:44 +08:00
2014-02-16 04:29:41 +08:00
/**
2014-11-18 07:46:46 +08:00
* Register callback for audio data.
2014-02-16 04:29:41 +08:00
*/
2014-11-29 20:42:19 +08:00
void toxav_register_audio_callback (ToxAv *av, ToxAvAudioCallback cb, void *userdata);
2014-02-16 04:29:41 +08:00
/**
2014-11-18 07:46:46 +08:00
* Register callback for video data.
*/
2014-11-29 20:42:19 +08:00
void toxav_register_video_callback (ToxAv *av, ToxAvVideoCallback cb, void *userdata);
2014-11-18 07:46:46 +08:00
/**
* Call user. Use its friend_id.
*/
int toxav_call(ToxAv *av,
int32_t *call_index,
2014-11-18 07:46:46 +08:00
int friend_id,
const ToxAvCSettings *csettings,
2014-11-18 07:46:46 +08:00
int ringing_seconds);
/**
* Hangup active call.
2014-02-16 04:29:41 +08:00
*/
2014-05-17 01:56:40 +08:00
int toxav_hangup(ToxAv *av, int32_t call_index);
2014-02-16 04:29:41 +08:00
/**
2014-11-18 07:46:46 +08:00
* Answer incoming call. Pass the csettings that you will use.
2014-02-16 04:29:41 +08:00
*/
2014-07-27 09:26:32 +08:00
int toxav_answer(ToxAv *av, int32_t call_index, const ToxAvCSettings *csettings );
2014-02-16 04:29:41 +08:00
/**
2014-11-18 07:46:46 +08:00
* Reject incoming call.
2014-02-16 04:29:41 +08:00
*/
2014-05-17 01:56:40 +08:00
int toxav_reject(ToxAv *av, int32_t call_index, const char *reason);
2014-02-16 04:29:41 +08:00
/**
2014-11-18 07:46:46 +08:00
* Cancel outgoing request.
2014-02-16 04:29:41 +08:00
*/
int toxav_cancel(ToxAv *av, int32_t call_index, int peer_id, const char *reason);
2014-02-16 04:29:41 +08:00
/**
2014-11-18 07:46:46 +08:00
* Notify peer that we are changing codec settings.
2014-02-16 04:29:41 +08:00
*/
2014-07-27 09:26:32 +08:00
int toxav_change_settings(ToxAv *av, int32_t call_index, const ToxAvCSettings *csettings);
2014-02-10 06:06:44 +08:00
2014-02-16 04:29:41 +08:00
/**
* Terminate transmission. Note that transmission will be
2014-11-18 07:46:46 +08:00
* terminated without informing remote peer. Usually called when we can't inform peer.
2014-02-16 04:29:41 +08:00
*/
2014-05-17 01:56:40 +08:00
int toxav_stop_call(ToxAv *av, int32_t call_index);
2014-02-10 06:06:44 +08:00
2014-02-16 04:29:41 +08:00
/**
2014-11-18 07:46:46 +08:00
* Allocates transmission data. Must be call before calling toxav_prepare_* and toxav_send_*.
* Also, it must be called when call is started
2014-02-16 04:29:41 +08:00
*/
2014-11-18 07:46:46 +08:00
int toxav_prepare_transmission(ToxAv *av, int32_t call_index, int support_video);
2014-02-10 06:06:44 +08:00
2014-02-16 04:29:41 +08:00
/**
2014-11-18 07:46:46 +08:00
* Clears transmission data. Call this at the end of the transmission.
2014-02-10 06:06:44 +08:00
*/
int toxav_kill_transmission(ToxAv *av, int32_t call_index);
2014-02-10 06:06:44 +08:00
2014-02-16 04:29:41 +08:00
/**
2014-11-18 07:46:46 +08:00
* Encode video frame.
2014-02-16 04:29:41 +08:00
*/
int toxav_prepare_video_frame ( ToxAv *av,
int32_t call_index,
uint8_t *dest,
int dest_max,
2014-11-18 07:46:46 +08:00
vpx_image_t *input);
2014-02-10 06:06:44 +08:00
2014-02-16 04:29:41 +08:00
/**
2014-11-18 07:46:46 +08:00
* Send encoded video packet.
2014-02-16 04:29:41 +08:00
*/
2014-11-18 07:46:46 +08:00
int toxav_send_video ( ToxAv *av, int32_t call_index, const uint8_t *frame, uint32_t frame_size);
2014-02-10 06:06:44 +08:00
2014-05-11 00:00:49 +08:00
/**
2014-11-18 07:46:46 +08:00
* Encode audio frame.
2014-05-11 00:00:49 +08:00
*/
int toxav_prepare_audio_frame ( ToxAv *av,
int32_t call_index,
uint8_t *dest,
int dest_max,
2014-11-18 07:46:46 +08:00
const int16_t *frame,
int frame_size);
2014-05-03 07:46:03 +08:00
/**
2014-11-18 07:46:46 +08:00
* Send encoded audio frame.
*/
int toxav_send_audio ( ToxAv *av, int32_t call_index, const uint8_t *frame, unsigned int size);
2014-02-10 06:06:44 +08:00
2014-02-16 04:29:41 +08:00
/**
2014-11-18 07:46:46 +08:00
* Get codec settings from the peer. These were exchanged during call initialization
* or when peer send us new csettings.
2014-02-16 04:29:41 +08:00
*/
2014-07-27 09:26:32 +08:00
int toxav_get_peer_csettings ( ToxAv *av, int32_t call_index, int peer, ToxAvCSettings *dest );
2014-02-16 04:29:41 +08:00
/**
2014-11-18 07:46:46 +08:00
* Get friend id of peer participating in conversation.
*/
int toxav_get_peer_id ( ToxAv *av, int32_t call_index, int peer );
2014-07-05 00:16:53 +08:00
/**
2014-11-18 07:46:46 +08:00
* Get current call state.
2014-07-05 00:16:53 +08:00
*/
ToxAvCallState toxav_get_call_state ( ToxAv *av, int32_t call_index );
2014-11-18 07:46:46 +08:00
2014-02-16 04:29:41 +08:00
/**
2014-11-18 07:46:46 +08:00
* Is certain capability supported. Used to determine if encoding/decoding is ready.
*/
int toxav_capability_supported ( ToxAv *av, int32_t call_index, ToxAvCapabilities capability );
2014-11-18 07:46:46 +08:00
/**
* Returns tox reference.
*/
Tox *toxav_get_tox (ToxAv *av);
2014-11-18 07:46:46 +08:00
/**
* Returns number of active calls or -1 on error.
*/
int toxav_get_active_count (ToxAv *av);
/* Create a new toxav group.
*
* return group number on success.
* return -1 on failure.
2014-11-11 22:48:52 +08:00
*
* Audio data callback format:
* audio_callback(Tox *tox, int groupnumber, int peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, unsigned int sample_rate, void *userdata)
*
* Note that total size of pcm in bytes is equal to (samples * channels * sizeof(int16_t)).
*/
int toxav_add_av_groupchat(Tox *tox, void (*audio_callback)(Tox *, int, int, const int16_t *, unsigned int, uint8_t,
unsigned int, void *), void *userdata);
/* Join a AV group (you need to have been invited first.)
*
* returns group number on success
* returns -1 on failure.
2014-11-11 22:48:52 +08:00
*
* Audio data callback format (same as the one for toxav_add_av_groupchat()):
* audio_callback(Tox *tox, int groupnumber, int peernumber, const int16_t *pcm, unsigned int samples, uint8_t channels, unsigned int sample_rate, void *userdata)
*
* Note that total size of pcm in bytes is equal to (samples * channels * sizeof(int16_t)).
*/
int toxav_join_av_groupchat(Tox *tox, int32_t friendnumber, const uint8_t *data, uint16_t length,
void (*audio_callback)(Tox *, int, int, const int16_t *, unsigned int, uint8_t, unsigned int, void *), void *userdata);
/* Send audio to the group chat.
*
* return 0 on success.
* return -1 on failure.
*
* Note that total size of pcm in bytes is equal to (samples * channels * sizeof(int16_t)).
*
* Valid number of samples are ((sample rate) * (audio length (Valid ones are: 2.5, 5, 10, 20, 40 or 60 ms)) / 1000)
* Valid number of channels are 1 or 2.
* Valid sample rates are 8000, 12000, 16000, 24000, or 48000.
*
* Recommended values are: samples = 960, channels = 1, sample_rate = 48000
*/
int toxav_group_send_audio(Tox *tox, int groupnumber, const int16_t *pcm, unsigned int samples, uint8_t channels,
unsigned int sample_rate);
2014-06-19 05:52:34 +08:00
#ifdef __cplusplus
}
#endif
2014-07-08 04:10:10 +08:00
#endif /* __TOXAV */