-
Notifications
You must be signed in to change notification settings - Fork 6
/
SINCallClient.h
197 lines (181 loc) · 7.77 KB
/
SINCallClient.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
/*
* Copyright (c) 2015 Sinch AB. All rights reserved.
*
* See LICENSE file for license terms and information.
*/
#import <Foundation/Foundation.h>
#import <Sinch/SINExport.h>
@class SINLocalNotification;
@protocol SINCall;
@protocol SINCallClientDelegate;
/**
* SINCallClient provides the entry point to the calling functionality of the Sinch SDK.
* A SINCallClient can be acquired via SINClient.
*
* ### Example
*
* id<SINClient> sinchClient;
* [sinchClient setSupportCalling:YES];
* [sinchClient start];
* ...
*
* // Place outgoing call.
* id<SINCallClient> callClient = [sinchClient callClient];
* id<SINCall> call = [callClient callUserWithId:@"<REMOTE USERID>"];
*
* // Set the call delegate that handles all the call state changes
* call.delegate= ... ;
*
* // ...
*
* // Hang up the call
* [call hangup];
*
*/
SIN_EXPORT SIN_EXTERN NSString *const SINIncomingCallNotification; // userInfo contains SINCall
SIN_EXPORT SIN_EXTERN NSString *const SINCallKey; // SINCallKey is used for SINCall in userInfo;
@protocol SINCallClient <NSObject>
/**
* The object that acts as the delegate of the call client.
*
* The delegate object handles call state change events and must
* adopt the SINCallClientDelegate protocol.
*
* @see SINCallClientDelegate
*/
@property (nonatomic, weak) id<SINCallClientDelegate> delegate;
/**
* Calls the user with the given id.
*
* @param userId The application specific id of the user to call.
*
* @exception NSInternalInconsistencyException Throws an exception if attempting
* to initiate a call before the
* SINClient is started.
* @see -[SINClientDelegate clientDidStart:].
* @return SINCall Outgoing call
*/
- (id<SINCall>)callUserWithId:(NSString *)userId;
/**
* Calls the user with the given id and the given headers.
*
* @param userId The application specific id of the user to call.
*
* @param headers NSString key-value pairs to pass with the call.
* The total size of header keys + values (when encoded with NSUTF8StringEncoding)
* must not exceed 1024 bytes.
*
* @exception NSInternalInconsistencyException Throws an exception if attempting
* to initiate a call before the
* SINClient is started.
* @see -[SINClientDelegate clientDidStart:].
*
* @exception NSInvalidArgumentException Throws an exception if headers are not strictly
* containing only keys and values that are of type NSString,
* or if the size of all header strings exceeds 1024 bytes when
* encoded as UTF-8.
*
* @return SINCall Outgoing call
*/
- (id<SINCall>)callUserWithId:(NSString *)userId headers:(NSDictionary *)headers;
/**
* Calls a phone number and terminates the call to the PSTN-network (Publicly Switched
* Telephone Network).
*
* @param phoneNumber The phone number to call.
* The phone number should be given according to E.164 number formatting
* (http://en.wikipedia.org/wiki/E.164) and should be prefixed with a '+'.
* E.g. to call the US phone number 415 555 0101, it should be specified as
* "+14155550101", where the '+' is the required prefix and the US country
* code '1' added before the local subscriber number.
*
* @exception NSInternalInconsistencyException Throws an exception if attempting
* to initiate a call before the
* SINClient is started.
* @see -[SINClientDelegate clientDidStart:].
* @return SINCall Outgoing call
*/
- (id<SINCall>)callPhoneNumber:(NSString *)phoneNumber;
/**
* Calls a phone number and terminate the call to the PSTN-network (Publicly Switched
* Telephone Network).
*
* @param phoneNumber The phone number to call.
* The phone number should be given according to E.164 number formatting
* (http://en.wikipedia.org/wiki/E.164) and should be prefixed with a '+'.
* E.g. to call the US phone number 415 555 0101, it should be specified as
* "+14155550101", where the '+' is the required prefix and the US country
* code '1' added before the local subscriber number.
*
* @param headers NSString key-value pairs to pass with the call.
* The total size of header keys + values (when encoded with NSUTF8StringEncoding)
* must not exceed 1024 bytes.
*
* @exception NSInternalInconsistencyException Throws an exception if attempting
* to initiate a call before the
* SINClient is started.
* @see -[SINClientDelegate clientDidStart:].
*
* @exception NSInvalidArgumentException Throws an exception if headers are not strictly
* containing only keys and values that are of type NSString,
* or if the size of all header strings exceeds 1024 bytes when
* encoded as UTF-8.
*
* @return SINCall Outgoing call
*/
- (id<SINCall>)callPhoneNumber:(NSString *)phoneNumber headers:(NSDictionary *)headers;
@end
@protocol SINCallClientDelegate <NSObject>
@optional
/**
* Tells the delegate that an incoming call has been received.
*
* To receive further events related to this call, a SINCallDelegate
* should be assigned to the call.
*
* The call has entered the `SINCallStateInitiating` state.
*
* @param client The client informing the delegate that an incoming call
* was received. The delegate of the incoming call object
* should be set by the implementation of this method.
*
* @param call The incoming call.
*
* @see SINCallClient, SINCall, SINCallDelegate
*/
- (void)client:(id<SINCallClient>)client didReceiveIncomingCall:(id<SINCall>)call;
/**
* Method for providing presentation related data for a local notification used
* to notify the application user of an incoming call.
*
* The return value will be used by SINCallClient to schedule a
* 'Local Push Notification', i.e. a UILocalNotification.
* That UILocalNotification, when triggered and taken action upon by the user,
* is supposed to be used in conjunction with
* -[SINClient relayLocalNotification:].
*
* This method is declared as optional, but it is still required to implement
* if support for using an active connection in background is enabled, see
* -[SINClient setSupportActiveConnectionInBackground:].
*
* Hanging up an incoming call while being in the background is a valid operation.
* This can be useful to dismiss an incoming call while the user is busy, e.g.
* in a regular phone call. This will effectively prevent the SDK from invoking
* the -[SINCallClientDelegate client:didReceiveIncomingCall:] method when the app returns to
* foreground.
* Invoking -[SINCall answer] is pended until the app returns to the foreground.
*
* @param client The client requesting a local notification
*
* @param call A SINCall object representing the incoming call.
*
* @return SINLocalNotification The delegate is responsible for composing a
* SINLocalNotification which can be used to
* present an incoming call.
*
* @see SINLocalNotification
* @see SINCallClient
* @see SINCall
*/
- (SINLocalNotification *)client:(id<SINCallClient>)client localNotificationForIncomingCall:(id<SINCall>)call;
@end