|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-6E221034-9A01-53AB-8374-315C38CCA21E" xml:lang="en"><title>Examples |
|
13 Showing the use of the SIP Profile API</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>The following sections describe how to use the SIP Profile API. </p> |
|
15 <ul> |
|
16 <li id="GUID-D5503066-5783-5D3D-9EC3-DBC7CEE398B3"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-82D83B96-FF89-5F6A-9A65-C448F103A2F5">Creating a SIP profile</xref> </p> </li> |
|
17 <li id="GUID-EE2733CC-B951-5970-BC00-2D8F3E0F6EFA"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-72003F70-79B8-5D23-977D-E736AD3E5B42">Modifying a SIP Profile</xref> </p> </li> |
|
18 <li id="GUID-6FCDC117-944D-57D6-BB49-77845972077E"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-27B07919-C5D5-5F8A-B2A3-AC2577E19C92">Enabling a SIP profile</xref> </p> </li> |
|
19 <li id="GUID-CBD94827-C48F-5E91-88F8-A2E962BB08B9"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-628DCA48-F8B4-5E6F-AC1B-731EAB1A9D62">Disabling a SIP profile</xref> </p> </li> |
|
20 <li id="GUID-610AAF1B-B350-5102-9DA4-82FBC04FC527"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-E607BA8F-50CC-5CF6-9D7E-E31319825507">Destroying a SIP Profile</xref> </p> </li> |
|
21 <li id="GUID-3108093C-35E5-56C2-A3C2-03527816E537"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-EABE2455-4D59-58AE-8D02-24FD4A7A82B1">Retrieving a profile</xref> </p> </li> |
|
22 <li id="GUID-1BE93BE1-2B70-53C8-B6FD-48278322517F"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-471F4EBB-2FE4-561D-9B74-555061797C45">Refreshing a SIP profile</xref> </p> </li> |
|
23 <li id="GUID-F6CD986B-C019-58E6-B71D-39F42AB03AA6"><p> <xref href="GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita#GUID-6E221034-9A01-53AB-8374-315C38CCA21E/GUID-289B2BF5-AF58-5E1E-B905-F1255EFC7FEB">Stopping SIP registration</xref> </p> </li> |
|
24 </ul> |
|
25 <section id="GUID-82D83B96-FF89-5F6A-9A65-C448F103A2F5"><title>Creating a |
|
26 SIP profile</title> <p> <xref href="GUID-5266AB0D-705C-3011-A92B-DA82BC212999.dita"><apiname> CSIPManagedProfileRegistry</apiname></xref> manages |
|
27 the SIP profiles and provides the functions to add, update, and remove profiles |
|
28 at run time. </p> <p>The following steps describes how to create a SIP profile. </p> <ol id="GUID-F9ECD3BD-52AC-5370-8336-4EEB619B1F58"> |
|
29 <li id="GUID-C0A00EF9-72F1-53DB-8CCB-BE7B4BF3D7F3"><p>Create a default profile |
|
30 that uses the <xref href="GUID-A9C883F9-3C6D-32BF-A278-4DCBDA18F687.dita"><apiname>CreateL()</apiname></xref> interface of <xref href="GUID-B2F66C7C-4E81-307C-B836-314D0A89D8D6.dita"><apiname>CSIPManagedProfileRegistry()</apiname></xref>. <xref href="GUID-A9C883F9-3C6D-32BF-A278-4DCBDA18F687.dita"><apiname>CreateL()</apiname></xref> returns |
|
31 an object of type <codeph>CSIPManagedProfile</codeph>. </p> </li> |
|
32 <li id="GUID-76CD5953-C5A9-51C0-9E66-2444AFE458D6"><p>Use <codeph>SetParameter()</codeph> of <xref href="GUID-CDE67614-1A7A-3082-8D8D-71645668A0DE.dita"><apiname>CSIPManagedProfile</apiname></xref> to |
|
33 set the value for the profile parameters. </p> </li> |
|
34 <li id="GUID-8F762BAF-0D4B-580D-8A8B-BE3B68C2BF90"><p>Use <xref href="GUID-5266AB0D-705C-3011-A92B-DA82BC212999.dita#GUID-5266AB0D-705C-3011-A92B-DA82BC212999/GUID-50D99686-5C79-3F7F-9C7D-4FC23EE41832"><apiname>CSIPManagedProfileRegistry::SaveL()</apiname></xref> to |
|
35 save the profile when the values are set. </p> </li> |
|
36 <li id="GUID-1B40AA8E-6326-5631-B83E-5230192FBC0E"><p>When you call <xref href="GUID-475D1AF4-F8C2-3243-99DC-43419979A858.dita"><apiname>SaveL()</apiname></xref>, |
|
37 wait until <xref href="GUID-92312598-A5DA-36B9-AF46-E7EE80452792.dita"><apiname>EProfileCreated</apiname></xref> event is reported in the observer. |
|
38 When the event is received the profile is created. </p> </li> |
|
39 </ol> <fig id="GUID-13F7B1AB-7F1A-544F-AC9C-26780E4FC517"> |
|
40 <image href="GUID-46A91D57-7864-53AD-903C-B978B0C61DAD_d0e342329_href.jpg" placement="inline"/> |
|
41 </fig> <p>The following code snippet shows how to create and save a profile. </p> <codeblock id="GUID-EFDEE0D4-00C9-520E-B1FA-18E48702DE7F" xml:space="preserve">/*Client must create an instance of the CSIP class. The API used for this is, here TUid must be an application UID.*/ |
|
42 |
|
43 CSIP* CSIP::NewL(const TUid& aUid, MSIPObserver& aObserver); |
|
44 |
|
45 /* CSIPManagedProfileRegistry manages SIP profiles and provides functions for adding, updating, or removing profiles at run time. */ |
|
46 |
|
47 iManagedProfileRegistry= CSIPManagedProfileRegistry::NewL(aObserver); |
|
48 |
|
49 /* CreateL() of CSIPManagedProfileRegistry is used to create a profile with default values. This takes ProfileType as parameter so define a profile type.*/ |
|
50 |
|
51 /* Profilename */ |
|
52 _LIT8( KProfileName, "ims" ); |
|
53 |
|
54 // Used to set and get the parameters of the profile |
|
55 CSIPManagedProfile* aProfile = NULL; |
|
56 |
|
57 // Set the profile type , profile name. |
|
58 TSIPProfileTypeInfo typeInfo; |
|
59 typeInfo.iSIPProfileClass = TSIPProfileTypeInfo:: EIms; |
|
60 typeInfo.iSIPProfileName = KProfileName; |
|
61 |
|
62 // Creates the profile of type IETF with default values |
|
63 aProfile = iManagedProfileRegistry->CreateL( typeInfo ); |
|
64 |
|
65 // Set the values in the newly created profile. |
|
66 TUint32 iapId(11); |
|
67 aProfile->SetParameter(KSIPAccessPointId,iapId); |
|
68 |
|
69 _LIT8(aor,"sip:user@192.168.0.35"); |
|
70 aProfile->SetParameter(KSIPUserAor,aor); |
|
71 |
|
72 // Save the profile |
|
73 iManagedProfileRegistry->SaveL(*aProfile); |
|
74 |
|
75 // Wait for EProfileCreated event on the observer. |
|
76 </codeblock> </section> |
|
77 <section id="GUID-72003F70-79B8-5D23-977D-E736AD3E5B42"><title>Modifying a |
|
78 SIP Profile</title> <p>The following steps describe how to modify a SIP profile. </p> <ol id="GUID-AFE64969-68F3-594C-8324-F0943694AB19"> |
|
79 <li id="GUID-FE7DBAA3-03C5-5CFC-BFB8-C63DDF7AA6A3"><p>The profile is modified |
|
80 when you change the profile parameters and save the updated profile to the |
|
81 permanent store. </p> </li> |
|
82 <li id="GUID-6B61FCF7-C753-534E-BF2D-293FE7A16F6E"><p>When the updated profile |
|
83 is saved to the permanent store the application gets the event notification <codeph>EProfileUpdated</codeph>. </p> </li> |
|
84 <li id="GUID-614CA2D4-ED93-58A7-B3FC-8F86C3BA3A7C"><p>Depending on the updated |
|
85 parameters, the update leads to no actions, to registration or to re-registration. |
|
86 The profile is re-registered if it is configured for auto-registration when |
|
87 the profile is updated. </p> </li> |
|
88 <li id="GUID-9A12EC08-7C67-551E-A7FE-5A114A36F721"><p>The profile must not |
|
89 be used by another application while you update the profile. Use the <xref href="GUID-5266AB0D-705C-3011-A92B-DA82BC212999.dita#GUID-5266AB0D-705C-3011-A92B-DA82BC212999/GUID-E6E0D735-28EC-3BFD-8359-68FDC39108EE"><apiname>CSIPManagedProfileRegistry::IsInUseL</apiname></xref> API |
|
90 to check if the profile is currently in use. </p> </li> |
|
91 </ol> </section> |
|
92 <section id="GUID-27B07919-C5D5-5F8A-B2A3-AC2577E19C92"><title>Enabling a |
|
93 SIP profile</title> <p>The following steps describe how to enable a SIP profile. </p> <ol id="GUID-1D340099-1F58-5E19-8380-1CC187CB7632"> |
|
94 <li id="GUID-7E306B08-C5A3-534F-9122-17D81BDAB5C2"><p>A client of the SIP |
|
95 Profile API must create a <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref> object. </p> <p> <b>Note</b>: |
|
96 The client must provide an instance of the class <xref href="GUID-AFB2603A-8A35-3E70-8EC2-229C9726F00B.dita"><apiname>CSIP</apiname></xref> to |
|
97 create an object of the type <codeph>CSIPProfileRegistry</codeph>. </p> </li> |
|
98 <li id="GUID-E8B43A46-B6F0-5466-A039-D0565EAA0895"><p>The client must implement |
|
99 the callback functions defined in the <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita"><apiname>MSIPProfileRegistryObserver</apiname></xref> interface |
|
100 to get notified when the status of the profile is changed. </p> </li> |
|
101 <li id="GUID-FDB514C2-5B6A-5FB6-AECD-BEF264DD700B"><p>Create an instance of <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref> using |
|
102 a retrieve function of the <xref href="GUID-DDB0FD0C-267F-3AAB-8519-78065180E0BD.dita"><apiname>CSIPPProfileRegistry</apiname></xref> class. </p> </li> |
|
103 <li id="GUID-B3B9F1DF-A195-5E37-84BD-2A951C472BC8"><p>The profile parameters |
|
104 are read from the getter functions of the <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref>. </p> </li> |
|
105 <li id="GUID-47997C80-FE84-5FAF-A5A1-E634215BD362"><p>The client can use the |
|
106 profile when you enable it through <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref> and |
|
107 leaves on failure. </p> </li> |
|
108 <li id="GUID-FBC081E2-D61E-58DB-9237-6673FB9231E0"><p>The user must check |
|
109 the profile status after the <xref href="GUID-93D33C84-8A6B-3A94-9797-1412489323F0.dita"><apiname>EnableL</apiname></xref> function is called. |
|
110 If the profile is not registered after this function is called, the user must |
|
111 wait until it gets a notification through the <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita"><apiname>MSIPProfileRegistryObserver</apiname></xref> callback |
|
112 interface about the profile registration. </p> </li> |
|
113 </ol> <fig id="GUID-9300C461-D490-5E0B-84A6-AD40F95B8DE7"> |
|
114 <image href="GUID-5C52B6B9-546C-5152-A968-B91CB3D885A0_d0e342464_href.jpg" placement="inline"/> |
|
115 </fig> <p>The following code snippet shows how to enable a SIP profile. </p> <codeblock id="GUID-1A52EE02-D6E9-5795-995B-6B5ADFD131B4" xml:space="preserve"> |
|
116 /*With the assumption that the profile was created and is saved to the persistent storage. */ |
|
117 //Create an Instance of SIP client |
|
118 |
|
119 iSip = CSIP::NewL( aAppUid ); |
|
120 |
|
121 //use CSIPProfileRegistry to get the saved profile. |
|
122 |
|
123 iProfileRegistry = CSIPProfileRegistry::NewL(*iSip, *this); |
|
124 |
|
125 //Retrieve the profiles by the AOR |
|
126 |
|
127 _LIT8(KAor,"sip:user@10.192.192.43"); |
|
128 TDesC8 aor(KAor); |
|
129 |
|
130 RPointerArray<CSIPProfile> profiles; |
|
131 |
|
132 /* Find and put the matching profiles by the given AOR into the pointer array. |
|
133 Returns the set of profiles which has the provided AOR.*/ |
|
134 |
|
135 iProfileRegistry->ProfilesL(KAor,profiles); |
|
136 |
|
137 // Check the profile count. Get the required profile if the count is positive non-zero. |
|
138 TInt profile_cnt = profiles.Count() ; |
|
139 iProfile = profiles[0]; |
|
140 iProfileRegistry->EnableL( *iProfile, *this ); |
|
141 |
|
142 //Application gets the event EProfileRegistered if the registration is successful. |
|
143 </codeblock> </section> |
|
144 <section id="GUID-628DCA48-F8B4-5E6F-AC1B-731EAB1A9D62"><title>Disabling a |
|
145 SIP profile</title> <p>The following steps describes how to disable a SIP |
|
146 profile. </p> <ul> |
|
147 <li id="GUID-8EF332BF-6FD9-50B2-B29C-A24B29B4829D"><p>A client of the SIP |
|
148 Profile API must create a <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref> object </p> <p> <b>Note</b>: |
|
149 The client must provide an instance of the class <xref href="GUID-AFB2603A-8A35-3E70-8EC2-229C9726F00B.dita"><apiname>CSIP</apiname></xref> to |
|
150 create a <xref href="GUID-E8D080AD-4494-3880-B5CE-3487CA7D76E9.dita"><apiname>CSIPProfileRegistry</apiname></xref> object. </p> </li> |
|
151 <li id="GUID-0715DDFB-639B-5843-BFC8-75E53D807698"><p>The client must implement |
|
152 the callback functions defined in the <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita"><apiname>MSIPProfileRegistryObserver</apiname></xref> interface |
|
153 to get notified with the events when the status of the profile is changed. </p> </li> |
|
154 <li id="GUID-8C06A1DB-BAE9-5718-B10D-3D262981B100"><p>Use retrieve function |
|
155 of the class <xref href="GUID-DDB0FD0C-267F-3AAB-8519-78065180E0BD.dita"><apiname>CSIPPProfileRegistry</apiname></xref> to create an instance |
|
156 of <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref>. </p> </li> |
|
157 <li id="GUID-4A1D7F52-7146-541C-91AE-E9CB5B8D5DD5"><p>The profile parameters |
|
158 are read from the getter functions of the <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref>. </p> </li> |
|
159 <li id="GUID-3D2ADA9A-DC9B-501D-B6DA-68BDA1B747FA"><p>Check the registration |
|
160 status of the profile that uses the getter functions of <xref href="GUID-68AE6070-0410-3671-9E68-A7785B8271CD.dita"><apiname>CSIPProfile</apiname></xref>. |
|
161 Disable the profile if it is registered. </p> </li> |
|
162 <li id="GUID-E042394C-6AF3-5951-8F26-C4473DBDD143"><p>An application gets |
|
163 the notification event <codeph>EProfileDeregistered</codeph> if the de-registration |
|
164 is successful, otherwise it leaves. The error is sent to the application through |
|
165 the <codeph>ProfileRegistryErrorOccurred</codeph> callback function. </p> </li> |
|
166 </ul> <p>The following code snippet shows how to disable a SIP profile. </p> <codeblock id="GUID-40C08581-81ED-5A7E-90D9-36966992191A" xml:space="preserve">/*With the assumption that the profile was created and is saved to the persistent storage. |
|
167 //Create an instance of SIP client |
|
168 iSip = CSIP::NewL( aAppUid |
|
169 |
|
170 /*use CSIPProfileRegistry to get the saved profile.*/ |
|
171 iProfileRegistry = CSIPProfileRegistry::NewL(*iSip, *this); |
|
172 |
|
173 /*Retrieve the profiles by the AOR*/ |
|
174 _LIT8(KAor,"sip:user@10.192.192.43"); |
|
175 TDesC8 aor(KAor); |
|
176 |
|
177 RPointerArray<CSIPProfile> profiles; |
|
178 |
|
179 // Find and put the matching profiles by the given AOR into the pointer array |
|
180 // Returns the set of profiles which has the provided AOR. |
|
181 iProfileRegistry->ProfilesL(KAor,profiles); |
|
182 |
|
183 /* Check the profile count. Get the required profile if the count is positive non-zero.*/ |
|
184 TInt profile_cnt = profiles.Count() ; |
|
185 iProfile = profiles[0]; |
|
186 |
|
187 // Registered is a bool type variable. Check the registration status of the iProfile. |
|
188 // Registered holds TRUE if it is registered otherwise FALSE |
|
189 iProfile->GetParameter( KSIPProfileRegistered, registered ); |
|
190 |
|
191 /* If the iProfile is registered ( the Registered variable must hold TRUE for iProfile )*/ |
|
192 /* Disable API returns KErrNone if the profile was disabled successfully otherwise there is a system-wide error.*/ |
|
193 CSIPProfileRegistry::Disable(*iProfile) |
|
194 </codeblock> </section> |
|
195 <section id="GUID-E607BA8F-50CC-5CF6-9D7E-E31319825507"><title>Destroying |
|
196 a SIP Profile</title> <p>When you destroy a SIP profile it is permanently |
|
197 removed from the permanent storage and it cannot be used. The profile information |
|
198 is removed from the <filepath>sipprofiles.dat</filepath> file in Epoc32\winscw\c\private\101F413C. </p> <p>The |
|
199 following steps describe how to destroy a SIP profile. </p> <ol id="GUID-04F9358C-2AED-58F7-9404-01A4588590D1"> |
|
200 <li id="GUID-3E72E3A2-3A3B-5433-8F38-6EB5AE517E50"><p>When the profile is |
|
201 destroyed the application gets the event <codeph>EProfileDestroyed</codeph>. </p> </li> |
|
202 <li id="GUID-D562B0C1-DC27-5615-AB19-70A978C4AF41"><ul> |
|
203 <li id="GUID-EDF14357-0BCB-539C-B569-01F19C02265E"><p>Registered: The removal |
|
204 is two-step process, de-register the profile and remove the profile. </p> </li> |
|
205 </ul> <ul> |
|
206 <li id="GUID-A1EC272B-AF21-572D-B16E-367EF21796BE"><p>De-registered : Removes |
|
207 the profile from the permanent storage and the application is notified with |
|
208 the event EProfileDestroyed. </p> </li> |
|
209 </ul> </li> |
|
210 </ol> <p>The following code snippet shows how to disable a profile. </p> <codeblock id="GUID-0784D25C-7AA0-53C1-B386-AC54F072833D" xml:space="preserve">//Function leaves on failure. |
|
211 CSIPManagedProfileRegistry::DestroyL(CSIPProfile& aSIPProfile); |
|
212 </codeblock> </section> |
|
213 <section id="GUID-EABE2455-4D59-58AE-8D02-24FD4A7A82B1"><title>Retrieving |
|
214 a profile</title> <p><b>Retrieving a default profile</b> </p> <p>The following |
|
215 code snippet shows how to retrieve the default profile. </p> <codeblock id="GUID-3D64A865-38B6-539F-8C6B-CE10996B24A3" xml:space="preserve">// Retrieving a default profile. |
|
216 CSIPProfile* profile = iProfileRegistry->DefaultProfileL(); |
|
217 |
|
218 // When a client retrieves a profile, its ownership is transferred to that client, so it becomes responsible |
|
219 // for deleting the instances when they are no longer needed. |
|
220 |
|
221 delete profile; |
|
222 </codeblock> <p><b>Retrieving profiles by type</b> </p> <p>The following code |
|
223 snippet shows how to retrieve profiles by type. </p> <codeblock id="GUID-26097346-72B3-51A9-ABB3-37B8B138B28D" xml:space="preserve">// To retrieve more than one profile, the client must create |
|
224 // an RPointerArray object to holding pointers to instances of CSIPProfile. |
|
225 |
|
226 RPointerArray<CSIPProfile> profiles; |
|
227 |
|
228 // The wanted type is defined using a variable of type TSIPProfileTypeInfo. |
|
229 |
|
230 TSIPProfileTypeInfo type; |
|
231 type.iSIPProfileClass = TSIPProfileTypeInfo::EInternet; |
|
232 type.iSIPProfileName = _L8("IETF"); |
|
233 |
|
234 // Profiles matching a given type are returned in the array. |
|
235 iProfileRegistry->ProfilesL(type, profiles); |
|
236 ... |
|
237 // When a client retrieves a profile, its ownership is transferred to that |
|
238 // client, so it becomes responsible for deleting the instances when they are |
|
239 // no longer needed. |
|
240 profiles.ResetAndDestroy(); |
|
241 </codeblock> <p><b>Retrieving profiles by matching an AOR</b> </p> <p>The |
|
242 following code snippet shows how to retrieve profiles by matching an AOR. </p> <codeblock id="GUID-71C88079-A622-5C95-B6C4-91066E99D021" xml:space="preserve">// To retrieve more than one profile, the client must create |
|
243 // an RPointerArray object to hold pointers to instances of CSIPProfile. |
|
244 RPointerArray<CSIPProfile> profiles; |
|
245 |
|
246 // Profiles matching a given AOR are returned in the array. |
|
247 iProfileRegistry->ProfilesL(_L8( "sip:jane.doe@foo.com" ), profiles ); |
|
248 ... |
|
249 |
|
250 // When a client retrieves a profile, its ownership is transferred to that |
|
251 // client, so it becomes responsible for deleting the instances when they are no longer needed. |
|
252 profiles.ResetAndDestroy(); |
|
253 </codeblock> </section> |
|
254 <section><title>Getting the registration events</title> <p>The following code |
|
255 snippet shows how to get the registration events for different scenarios. </p> <codeblock id="GUID-4BCCE827-AD41-5DB0-A71F-611F1DF4BE25" xml:space="preserve">// A callback function, which must be implemented by the client, is called when the registration status |
|
256 of a profile owned by the client is changed. |
|
257 |
|
258 void CMySIPClient:: ProfileRegistryEventOccurred(TUint32 aProfileId, |
|
259 MSIPProfileRegistryObserver::TEvent aEvent) |
|
260 { |
|
261 iProfileId = aProfileId; |
|
262 switch(aEvent) |
|
263 { |
|
264 case EProfileCreated: |
|
265 { |
|
266 iEventId = EAdded; |
|
267 break; |
|
268 } |
|
269 case EProfileUpdated: |
|
270 { |
|
271 iEventId = EUpdated; |
|
272 break; |
|
273 } |
|
274 case EProfileRegistered: |
|
275 { |
|
276 iEventId = CMySIPClient::ERegistered; |
|
277 break; |
|
278 } |
|
279 case EProfileDeregistered: |
|
280 { |
|
281 iEventId = CMySIPClient::EDeregistered; |
|
282 break; |
|
283 } |
|
284 case EProfileDestroyed: |
|
285 { |
|
286 iEventId = ERemoved; |
|
287 break; |
|
288 } |
|
289 default: |
|
290 break; |
|
291 } |
|
292 }</codeblock> </section> |
|
293 <section id="GUID-471F4EBB-2FE4-561D-9B74-555061797C45"><title>Refreshing |
|
294 a SIP profile</title> <p>The SIP profile can use either WLAN or GPRS connections |
|
295 to register to the SIP server. In case of WLAN, a registered SIP profile changes |
|
296 its state to an unregistered state when the handset is out of WLAN coverage. |
|
297 On re-entering the WLAN zone, the WLAN automatically scans to identify the |
|
298 available access points and then the SIP profile is automatically registered |
|
299 back with the server. This process is time consuming and is not efficient. |
|
300 So, the client uses the <xref href="GUID-1AEB6899-9942-3BBC-9ABA-8C0ACFCE3174.dita"><apiname>RefreshEnableL()</apiname></xref> function to: </p> <ul> |
|
301 <li id="GUID-A19E0054-71CA-55A4-BF75-9481189D81DC"><p>Initiate the SIP registration |
|
302 automatically. </p> </li> |
|
303 <li id="GUID-E42A6C7C-0238-5C33-9CDA-4691801D8E04"><p>Reduce the response |
|
304 time for the SIP registration. </p> </li> |
|
305 <li id="GUID-54F38CF7-D29D-5D30-954E-D7DD88D6B022"><p>Improve the efficiency |
|
306 of the application using the SIP stack during registration. </p> </li> |
|
307 </ul> <p>The <xref href="GUID-D5A82B9C-A86E-318F-85D7-B9DC69968DB0.dita"><apiname>RefreshEnableL</apiname></xref> API refreshes the connection |
|
308 on the used access point if it is not active. Refresh enabling a profile means |
|
309 that the user has enabled the profile but is unregistered because of a connection |
|
310 loss. For example, in a WLAN network, a connection refresh request to the |
|
311 bearer monitor starts the WLAN scanning if it is stopped. When the Connection |
|
312 Active notification is received, the stack automatically registers the profile |
|
313 and gives a notification to the client with the event <xref href="GUID-F78ECFEB-441F-3D55-9909-A3F82F738F7E.dita"><apiname>EProfileRegistered</apiname></xref> through |
|
314 the <xref href="GUID-91663686-42B7-3C88-B773-3C5343CDCFCE.dita"><apiname>MSIPProfileRegistryObserver</apiname></xref>. </p> <p>To refresh enable |
|
315 a profile, do the following steps: </p> <ul> |
|
316 <li id="GUID-221E3B9E-86DF-5200-ADA6-55E724688028"><p>Start the SIP Profile |
|
317 server. </p> </li> |
|
318 <li id="GUID-59833E8F-9619-5C72-8891-2E2D63B6B8CF"><p>Fetch the profile that |
|
319 must be refresh enabled from the SIP Profile Server. </p> <ul> |
|
320 <li id="GUID-0C52D86D-3ADA-5D6D-AEC5-07D1554A9C11"><p>If the profile is not |
|
321 Enabled the <xref href="GUID-E72E5C9A-ADAE-346A-8EF9-DACD7D23F318.dita"><apiname>RefreshEnable</apiname></xref> API leaves with <codeph>KErrArgument</codeph> error. </p> </li> |
|
322 <li id="GUID-EFC454B5-6F99-58A3-B3ED-9983DE0C1A4E"><p>If the profile is Enabled |
|
323 and in a Registered state then the API leaves with <codeph>KErrAlreadyExists</codeph> error. </p> </li> |
|
324 <li id="GUID-6B5728C4-F42C-5208-A6E4-1AF5641A13E3"><p>If the profile is Enabled |
|
325 and in an Unregistered state then the <xref href="GUID-E72E5C9A-ADAE-346A-8EF9-DACD7D23F318.dita"><apiname>RefreshEnable</apiname></xref> API |
|
326 refreshes the connection through <xref href="GUID-2A070F4D-A35B-3505-BE86-E6C7A2F27B94.dita#GUID-2A070F4D-A35B-3505-BE86-E6C7A2F27B94/GUID-956F2ADC-40D6-3C15-949A-80789DF04550"><apiname>CSIPConnection::RefreshConnection()</apiname></xref> API. |
|
327 The profile receives notification about the active connection and it automatically |
|
328 registers again and sends <xref href="GUID-F78ECFEB-441F-3D55-9909-A3F82F738F7E.dita"><apiname>EProfileRegistered</apiname></xref> event to the |
|
329 application. </p> </li> |
|
330 </ul> </li> |
|
331 <li id="GUID-9CA4CA87-17C7-54D0-AEAF-F415DA5D934E"><p>A REGISTER request sent |
|
332 to the registrar server. </p> </li> |
|
333 <li id="GUID-FF40934C-588D-5ED6-8041-410103FB6D53"><p>The registration status |
|
334 of the profile is set to Registered. </p> </li> |
|
335 </ul> <p>The following sequence diagram shows how to enable a profile to refresh. </p> <fig id="GUID-5EF1953C-E56D-59C2-B443-F1B77DD7E73D"> |
|
336 <image href="GUID-8D9FE811-3F8A-5C2A-B76A-5C0248179590_d0e342779_href.jpg" placement="inline"/> |
|
337 </fig> <p>The following code describes how to refresh enable a profile. </p> <codeblock id="GUID-1A13F3D3-C4B7-50E5-B5AF-F0CABF02758C" xml:space="preserve">//Checks if the profile is already enabled and requests the Profile Agent to refresh it. |
|
338 // If the profile is not enabled it leaves with KErrArgument. |
|
339 |
|
340 void RefreshEnableL(CSIPProfile& aSIPProfile, MSIPConnectionObserver& aObserver) |
|
341 </codeblock> </section> |
|
342 <section id="GUID-289B2BF5-AF58-5E1E-B905-F1255EFC7FEB"><title>Stopping SIP |
|
343 registration</title> <p>In a setup, where there is no registrar, the SIP stack |
|
344 tries to send REGISTER messages to the network for at least 3 minutes and |
|
345 reserves the access point usage. During these 3 minutes the client cannot |
|
346 use another WLAN access point without destroying the <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref>. </p> <p>The <xref href="GUID-A36FEEBB-C9E1-3C99-9B9E-09C7530F31C4.dita"><apiname>ForceDisable</apiname></xref> API |
|
347 of the SIP stack stops all registration attempts and releases the access point. |
|
348 The <xref href="GUID-A36FEEBB-C9E1-3C99-9B9E-09C7530F31C4.dita"><apiname>ForceDisable</apiname></xref> API in the profile agent module improves |
|
349 the responsiveness of the applications using the SIP stack. It avoids situations |
|
350 where an application is waiting for the SIP stack to complete a registration |
|
351 procedure. </p> <p>To use the <xref href="GUID-A36FEEBB-C9E1-3C99-9B9E-09C7530F31C4.dita"><apiname>ForceDisable</apiname></xref> API the application |
|
352 must have Network Control capability. If the application does not have Network |
|
353 Control capability and invokes the <xref href="GUID-A36FEEBB-C9E1-3C99-9B9E-09C7530F31C4.dita"><apiname>ForceDisable</apiname></xref> API, then |
|
354 it receives <codeph>ErrPermissionDenied (-46</codeph>) error. Sending a <xref href="GUID-A36FEEBB-C9E1-3C99-9B9E-09C7530F31C4.dita"><apiname>ForceDisable</apiname></xref> API |
|
355 does not force the SIP stack to send any message to the network, instead it |
|
356 destroys the SIP transaction for that profile and cleans all the resources |
|
357 associated with that profile. The Profile Agent also notifies all the observers |
|
358 with the event <xref href="GUID-1B01576C-59DC-3958-9631-3094ED0DB46D.dita"><apiname>EProfileForciblyDisabled</apiname></xref>. </p> <p>The following |
|
359 code describes how to forcibly disable a profile. </p> <codeblock id="GUID-3D1556EB-AD13-5640-8104-83D08BF0D207" xml:space="preserve">// With the assumption that the profile is created and is saved to the persistent storage create an instance of the SIP client |
|
360 iSip = CSIP::NewL( aAppUid ); |
|
361 |
|
362 // Use CSIPProfileRegistry to get the saved profile. |
|
363 iProfileRegistry = CSIPProfileRegistry::NewL(*iSip, *this); |
|
364 |
|
365 // Retrieve the profiles by the AOR |
|
366 _LIT8(KAor,"sip:user@10.192.192.43"); |
|
367 TDesC8 aor(KAor); |
|
368 RPointerArray<CSIPProfile> profiles; |
|
369 |
|
370 // Find and add the matching profiles by the given AOR into the pointer array |
|
371 // Returns the set of profiles which has the provided AOR. |
|
372 iProfileRegistry->ProfilesL(KAor,profiles); |
|
373 |
|
374 // Check the profile count. Get the required profile if the count is positive non-zero. |
|
375 TInt profile_cnt = profiles.Count() ; |
|
376 iProfile = profiles[0]; |
|
377 |
|
378 // If the iProfile is registered (the Registered variable must hold TRUE for iProfile) |
|
379 // Disable API returns KErrNone if the profile is disabled successfully otherwise there is a system-wide error. |
|
380 CSIPProfileRegistry::ForceDisable(*iProfile);</codeblock> </section> |
|
381 </conbody></concept> |