內(nèi)容教程成果

ETelCoreAPIDesign

SecurityClassification:DocumentReference:

InternalN/A

Status:Version:

Issued1.6

Team/Department:Author(s):

<ConvergedComms>

<AndrewCloke,MatthewSwan,KatieSheehy,NathalieDoyelle,ShaziaBhatti,NeilMcAlpine,AleksandarAntonic,

RavishankarLakshminarayanan>

<DejanaSerdarevic>

Owner(s):

Approver(s):

<DejanaSerdarevic>

Distribution:

<ConvergedCommsTeam,licensees>

Copyright?2009NokiaCorporationand/oritssubsidiary(-ies).Allrightsreserved.

Thiscomponentandtheaccompanyingmaterialsaremadeavailableunderthetermsof"EclipsePublicLicensev1.0"whichaccompaniesthisdistributionandisavailableattheURL

“http:/

/

/legal/epl-v10.html

”.

InitialContributors:

Nokia-initialcontribution.

ETELCOREAPIDESIGN

INTERNAL

ISSUEDREV1.6

Contents

1

INTRODUCTION 5

2

SERVERREQUESTS 5

2.1

2.2

2.3

2.4

2.5

2.6

2.7

2.8

2.9

2.10

2.11

2.12

CONNECTINGTOTHESERVER 5

RETRIEVEVERSIONINFORMATION 5

ENUMERATEPHONES 5

GETPHONEINFORMATION 5

GETNAMEOFTSYBYPHONE 5

LOADPHONEMODULE 6

UNLOADPHONEMODULE 6

QUERYTSYABOUTSUPPORTEDFUNCTIONALITY 6

SETACLIENTTOBETHEPRIORITYCLIENT 6

SETACLIENT’SDESIREDERRORGRANULARITY 7

RETRIEVEVERSIONINFORMATIONOFTSY 7

DISCONNECTINGFROMTHESERVER 7

3

PHONEREQUESTS 8

3.1

3.2

3.3

3.4

3.5

3.6

3.7

3.8

3.9

3.10

3.11

3.12

3.13

OPENAPHONE 錯(cuò)誤!未定義書簽。

CONTROLLEDINITIALISATION 錯(cuò)誤!未定義書簽。

CANCELANINITIALIZEREQUEST 錯(cuò)誤!未定義書簽。

SETACLIENTTOBETHEEMERGENCYCLIENT 8

RETRIEVECAPABILITYINFORMATION 錯(cuò)誤!未定義書簽。

CAPABILITIESCHANGENOTIFICATION 錯(cuò)誤!未定義書簽。

CANCELACAPABILITIESCHANGENOTIFICATION 錯(cuò)誤!未定義書簽。

RETRIEVESTATUSINFORMATION 錯(cuò)誤!未定義書簽。

ENUMERATELINES 錯(cuò)誤!未定義書簽。

RETRIEVELINEINFORMATION 錯(cuò)誤!未定義書簽。

MODEMDETECTIONNOTIFICATION 錯(cuò)誤!未定義書簽。

CANCELAMODEMDETECTIONNOTIFICATION 錯(cuò)誤!未定義書簽。

PHONECLASSMEMBERDATA 錯(cuò)誤!未定義書簽。

3.13.1

GetCurrentPhoneInformation 錯(cuò)誤!未定義書簽。

3.14 CLOSEAPHONE 錯(cuò)誤!未定義書簽。

LINEREQUESTS 12

4

4.1

4.2

4.3

4.4

4.5

4.6

4.7

4.8

4.9

4.10

4.11

4.12

4.13

4.14

4.15

4.16

4.17

OPENALINE 12

RETRIEVELINECAPABILITIES 12

CAPABILITIESCHANGENOTIFICATION 12

CANCELACAPABILITIESCHANGENOTIFICATION 12

RETRIEVESTATUSINFORMATION 12

RETRIEVEHOOKSTATUS 13

ENUMERATINGCALLS 13

RETRIEVECALLINFORMATION 13

INCOMINGCALLNOTIFICATION 13

CANCELINCOMINGCALLNOTIFICATION 13

HOOKCHANGENOTIFICATION 13

CANCELAHOOKCHANGENOTIFICATION 14

LINESTATUSNOTIFICATION 14

CANCELLINESTATUSNOTIFICATION 14

NEWCALLADDEDNOTIFICATION 14

CANCELNEWCALLADDEDNOTIFICATION 14

LINECLASSMEMBERDATA 14

4.17.1

GetCurrentLineInformation 14

4.18 CLOSEALINE 15

?NOKIACORPORATIONAND/ORITSSUBSIDIARIES

2

ETELCOREAPIDESIGN

INTERNAL

ISSUEDREV1.6

5

CALLREQUESTS 16

5.1

5.2

5.3

5.4

5.5

5.6

5.7

5.8

5.9

5.10

5.11

5.12

5.13

5.14

OPENACALL 16

RETRIEVECALLSTATUS 16

RETRIEVECALLCAPABILITIES 16

CAPABILITIESCHANGENOTIFICATION 17

CANCELACAPABILITIESCHANGENOTIFICATION 17

RETRIEVEBEARERSERVICEINFO 17

HOOKCHANGENOTIFICATION 18

CANCELHOOKCHANGENOTIFICATION 18

CALLSTATUSNOTIFICATION 18

CANCELCALLSTATUSNOTIFICATION 18

CALLDURATIONCHANGENOTIFICATION 18

CANCELCALLDURATIONCHANGENOTIFICATION 18

RETRIEVECALLDURATION 19

CALLCLASSMEMBERDATA 19

5.14.1

GetCurrentCallInformation 19

5.15

5.16

5.17

5.18

5.19

5.20

5.21

5.22

5.23

5.24

5.25

5.26

5.27

5.28

5.29

5.30

5.31

5.32

5.33

5.34

5.35

DIALACALL 19

CANCELDIALCALLCOMMAND 19

IMMEDIATECONNECT 19

CANCELIMMEDIATECONNECT 20

ANSWERACALL 20

CANCELCALLANSWER 20

TERMINATEANACTIVECALL 20

CANCELCALLTERMINATE 20

LOANINGTHECOMMUNICATIONPORTTOTHECLIENT 21

CANCELLOANCOMMUNICATIONSPORT 21

RECOVERINGALOANEDCOMMUNICATIONSPORT 21

ACQUIRINGCALLOWNERSHIP 21

CANCELACQUIRECALLOWNERSHIP 22

TRANSFEROWNERSHIP 22

RETRIEVEOWNERSHIPINFORMATION 22

RETRIEVECALLPARAMETERS 22

RETRIEVEFAXSETTINGS 23

SETFAXSETTINGS 24

RETRIEVEREFERENCECOUNT 24

CLOSEACALL 24

ADOPTFAXHEADERFILEINFAXSERVER 24

6

FAXREQUESTS 25

6.1

6.2

6.3

6.4

6.5

6.6

6.7

OPENAFAXPORT 25

READFAXINFORMATION 25

WRITEFAXINFORMATION 25

WAITFORTHEENDOFAPAGE 25

CANCELTHEFAXSESSION 25

RETRIEVEFAXPROGRESSINFORMATION 25

CLOSEAFAXOBJECT 26

7

CALLOWNERSHIP 27

7.1

7.2

7.3

7.4

7.5

7.6

OVERVIEW 27

CALLOWNERSHIPSCENARIOS 28

SIMPLECALLOWNERSHIPEXAMPLE 28

CALLOWNERSHIPTRANSFEREXAMPLE 30

CLIENTPANICEXAMPLEA 32

CLIENTPANICEXAMPLEB 34

8

FAXSESSIONEXAMPLES 36

8.1

8.2

FAXDIALLINGANDTRANSMISSION 36

FAXANSWERINGANDRECEIVINGEXAMPLE 38

?NOKIACORPORATIONAND/ORITSSUBSIDIARIES

3

ETELCOREAPIDESIGN

INTERNAL

ISSUEDREV1.6

9 ETELCOREERRORMESSAGES 42

10

ETELUTILITIES 43

10.1 TLVSTRUCTURESUPPORT 43

11

ETELUDEBLOGGING 46

V9.1ANDBELOW:FLOGGER1 46

V9.2ANDABOVE:CDULOGGING 47

12

REFERENCES 48

13

REVISIONHISTORY 48

14

14.1

14.2

14.3

14.4

14.5

14.6

FURTHERINFORMATION 49

PEOPLE 49

REFERENCES 49

OPENISSUES 49

GLOSSARY 錯(cuò)誤!未定義書簽。

DOCUMENTHISTORY 49

DOCUMENTREVIEWDATE 49

?NOKIACORPORATIONAND/ORITSSUBSIDIARIES

4

ETELCOREAPIDESIGN

INTERNAL

ISSUEDREV1.6

1

Introduction

ThisdocumentdescribesthecoreETelAPI,itsfunctionsandclassabstraction.Asectionisdevotedtoeachoftheclassabstractions:phones,lines,callandfaxfunctionality.Additionalsectionsthengiveexamplesthatillustratethemechanicsofcallownershipandfaxsessions.

2 ServerRequests

2.1 ConnectingtotheServer

TIntRTelServer::Connect(TIntaMessageSlots)

ThisfunctionconnectstheclienttotheETelServerwiththespecifiednumberofmessageslots.Itmustbeusedbeforeanyoftheotherfunctionslistedinthisdocument.

2.2

RetrieveVersionInformation

TVersionRTelServer::Version()

ThisfunctionreturnstheversionnumberoftheETelServerintheTVersionstructure.

2.3

EnumeratePhones

TIntRTelServer::EnumeratePhones(TInt&aCount)

ThisfunctionreturnsthetotalnumberofphonesupportedbyalltheETel(TSY)modulescurrentlyloaded.ThenumberisreturnedintheaCountvariable.

2.4

GetPhoneInformation

TIntRTelServer::GetPhoneInfo(TIntaIndex,TPhoneInfo&aInfo)

ThisfunctionreturnsinformationassociatedwiththephoneindicatedbytheaIndexvariable.ThephoneinformationisreturnedintheaInfostructure,describedbelow.

2.5 GetNameofTSYbyPhone

TIntRTelServer::GetTsyName(constTIntaIndexOfPhone,TDes&aTsyName)

ThisfunctionreturnsthenameoftheTSYmodulethatthephoneindicatedbytheindexaIndexOfPhonebelongsto.

?NOKIACORPORATIONAND/ORITSSUBSIDIARIES

5

iNetworkType

Thetypeoftelephonyconnectionsupportedbythephone.Thismaytakeoneofthefollowingvalues:

ENetworkTypeWiredAnalog

ENetworkTypeWiredDigital

ENetworkTypeMobileAnalog

ENetworkTypeMobileDigital

ENetworkTypeUnknown

iName

Thenameofthephone.

iNumberOfLines

Thenumberoflinessupportedbythephone.

iExtensions

TheextensionsthattheTSYmodulesupports.

Variable Description

ETELCOREAPIDESIGN

INTERNAL

ISSUEDREV1.6

2.6 LoadPhoneModule

TIntRTelServer::LoadPhoneModule(constTDesC&aName)

ThisfunctionloadstheETel(TSY)modulespecifiedbytheaNamevariable.ThenameneednotincludetheTSYextension,thiswillbeaddedbytheserver.Onceloaded,informationaboutthephone(s)addedbythemodulecanbeaccessedusingtheEnumeratePhonesandPhoneInfofunctions.

2.7 UnloadPhoneModule

TIntRTelServer::UnloadPhoneModule(constTDesC&aName)

ThisfunctionunloadstheETel(TSY)modulespecifiedbytheaNamevariable.ThenameneednotincludetheTSYextension,thiswillbeaddedbytheserver.

2.8 QueryTSYaboutSupportedFunctionality

TIntRTelServer::IsSupportedByModule(constTDesC&aTsyName,constTIntaMixin,TBool&aResult)

ThisfunctionallowsaclienttoqueryaTSYmoduleaboutwhattypeofextendedfunctionalityitsupports.ItisassumedtheTSYmodulewillsupportallcorefunctionality.TheaMixinparameterisanintegerdefinedinapublicheaderfileavailablebothtotheclientandtheTSYwhichrepresentsalimitedsubsetoffunctionality,andtheaResultparameterispassedbackaseitherTRUEorFALSE.ThefunctionwillreturnKErrNotFoundiftheTSYmodulespecifiedisnotavailable.

2.9 SetaClienttobethePriorityClient

TIntRTelServer::SetPriorityClient()

Thisfunctionisarequesttotheservertoallocateprioritystatustotheclientwhichcallsit.Theprioritystatusallowstheclienttobecomethepriorityclientintheplatformandbegrantedcontroloveranycall.

Onlyoneclientinthesystemmayhavethisprioritystatus,andthatwouldtypicallybethedefaultphoneapplication.Thatiswhythismethodhasitsaccessrestrictedtoallowonlythedefaultphoneapplicationtosuccessfullycallthismethod–themethodispolicedwiththeNetworkControlcapability+theSIDofthedefaultphoneapplication.ThismeansthatonlytheclientwiththerequiredcapabilityandtherequiredSIDwillbeabletosuccessfullycallthismethod.IfanotherapplicationattemptstocallthisAPI,thisfunctionwillreturnKErrPermissionDenied.IfthepriorityclientcallsthisAPImorethenonce,thefunctionwillreturnKErrAlreadyExists.

Whenthismethodiscalled,theETelserverwillalsopreallocateextramemorytobeusedfortheemergencyrequestsmadebythepriorityclient,forexampleanemergencydialrequest.Ifthepriorityclientthencallsan“emergency”request(ofwhichtherearenoneinthecoreETelAPI),theserverwillusethepreallocatedmemoryfortherequestratherthanallocatingextramemorytopreventanoutofmemoryerror.Ifthepre-allocationofmemorywithinthismethodfails,thereturnerrorwillbeKErrNoMemory.Other,non-priority,clientsthatneedtohandleemergencyrequestsandwishtopreallocateenoughmemoryfortheiremergencyrequesthandlingshouldusetheRPhone::SetEmergencyClient()method.

Notetothedefaultphoneappdevelopers:

ToenabletheSIDofthedefaultphoneapplicationtobeeasilyoverwrittenbythedefaultphoneappdevelopers,theSIDwillalsobedefinedasapatchdataintheetel.ibyfileasfollows:

patchdataetel.dll@KPriorityClientSid<0x12345678>

where0x12345678isanexampleSIDofthedefaultphoneapp.

Thedefaultphoneappdevelopersareexpectedtomodifytheetel.ibyfilepriortoROMbuildingandreplacethedefaultSIDvaluewiththeSIDvalueoftheirdefaultphoneapp.

Toenabletestingofthisfunctionalityontheemulatortheepoc.inifileneedstobemodifiedtodefinethefollowingproperty:

?NOKIACORPORATIONAND/ORITSSUBSIDIARIES

6

ETELCOREAPIDESIGN

INTERNAL

ISSUEDREV1.6

etel_KPriorityClientSid0x12345678

where0x12345678isanexampleSIDvalueoftheirdefaultphoneapp.

2.10SetaClient’sdesirederrorgranularity

TIntRTelServer::SetExtendedErrorGranularity(RTelServer::TErrorGranularityaGranularity)const

Thisfunctionisarequesttotheservertoregisterthespecifiederrorgranularityagainsttheclientwhichcallsit.TheETelserverwillprovideextendederrors(i.e.proprietaryclient/TSYerrordefinitionsoutsideoftheETelcoreerrorspace)toaclientthatcallsthismethodandspecifiesaGranularityequaltoEErrorExtended.Afterregisteringinterestinextendederrors,this“advanced”clientwillreceiveanextendederrorcodewheneveroneoftheirrequestsendsinanerrorthatistranslatedbytheTSYintooneoftheproprietaryextendederrorcodes.IfanerroroccursthattheTSYcannottranslateintoanextendederrorthentheTSYwillreturnoneofthebasicerrorsinstead.Forthisreason,thebasicerrorspaceandtheextendederrorspacemustnotclash.AclientwhichhasnotcalledthismethodoronewhichspecifiesaGranularityequaltoEErrorBasicwillonlyreceiveerrorsfromthesmallsetofETelandBasebasicerrors.

BasicerrorcodesarethoseusedanddefinedbytheETelCoreAPI.TheseerrorcodesalongsidetheE32Basesetoferrorcodescollectivelyformthebasicerrorspace.TheerrorcodesdefinedintheETelextensions,suchasETelMM,ETelSAT,ETelPacketexterror.hinETel,aswellasthosedefinedbyLicensees,collectivelyformtheextendederrorspace.Thelicenseedefinedextendederrorspacehasarangeof-21000to-29999.

2.11RetrieveVersionInformationofTSY

TIntRTelServer::GetTsyVersionNumber(constTDesC&aTsyName,TVersion&aVersion)const;

ThisfunctionreturnstheversionnumberofthespecifiedTSYmoduleintheaVersionparameter.

2.12DisconnectingfromtheServer

TIntRTelServer::Close()

Thisfunctionclosestheclient’shandleontheserver.

?NOKIACORPORATIONAND/ORITSSUBSIDIARIES

7

EErrorBasic

Clientisonlyinterestedincoreerrors

EErrorExtended

Clientisinterestedinextendederrors

TErrorGranularity Description

ETELCOREAPIDESIGN

INTERNAL

ISSUEDREV1.6

3 PhoneRequests

3.1 OpenaPhone

TIntRPhone::Open(RTelServer&aSession,constTDesC&aName)

ThisfunctionopensthephonespecifiedbytheaNamevariable.TheaSessionvariablemustspecifyaserversessionwhichisconnectedtotheserver.

3.2 ControlledInitialisation

TIntRPhone::Initialise()

voidRPhone::Initialise(TRequestStatus&aStatus)

Thisfunctionallowstheclienttocontrolwhenaphoneisinitialised,orre-initialised.Thephonehardwareisusuallyautomaticallyinitialisedbeforethefirstcommandissent.However,thisoperationcantakeanumberofseconds,andmaythereforecauseasluggishresponse.Thiscommandgivesaclienttheabilitycontroltheinitialisationtiming.

Aclientmaywishtoknowwhentheautomaticinitializedfunctionhascompleted,sothatitmaycallasynchronousfunctionthatobeysflowcontrol.Itcandothisbycallingthisfunctionduringtheautomaticsequence,whichwillthencompleteimmediatelyuponinitialisationwithoutexecutingitasecondtime.

3.3 CancelanInitializeRequest

voidRPhone::InitialiseCancel()

Thisfunctioncancelsarequesttoinitialisethemodem,placedusingtheasynchronousvariantoftheInitialisefunction.

3.4 SetaClienttobetheEmergencyClient

TIntRPhone::SetEmergencyClient(constTUint32aEmergencyRequest)

ThismethodallowstheclienttoinstructtheETelserverandtheTSYtopreallocateextramemoryforanypotentialemergencyrequesthandlingfromthisclient.Itallowsother,non-priority,clientswhooperateunderemergencyconditions,tohavememorypreallocatedforthemintheETelserver.TherequestgetspasseddowntotheTSY,sothattheTSYcanalsoproceedwiththenecessarymemorypre-allocation.

?NOKIACORPORATIONAND/ORITSSUBSIDIARIES

8

TEmergencyRequests

Description

EEmergencyLCSRequest

=0x00000001

PreallocateenoughmemoryinETelandTSYfortheLCS(LocationServices)emergencyrequesthandling.

AfterthisAPIiscalledthepreallocatedmemorywillbeusedtoservicethefollowingemergencyLCSrequests:

RMobileLocationServices::NotifyMtlr()RMobileLocationServices::SendMtlrResponse()RMobileLocationServices::NotifyMeasurementControl()RMobileLocationServices::SendMeasurementReport()

EEmergencyCSVoiceCallRequest

=0x00000002

PreallocateenoughmemoryinETelandTSYfortheCircuitSwitchedVoiceCallemergencyrequesthandling.

AfterthisAPIiscalledthepreallocatedmemorywillbeusedtoservicethefollowingemergencyCircuitSwitchedVoiceCallemergencyrequests:

RMobileCall::DialEmergencyCall()

ETELCOREAPIDESIGN

INTERNAL

ISSUEDREV1.6

TheclientspecifiesthetypeofemergencyrequeststhatitwishestohandleintheaEmergencyRequestparameter.aEmergencyRequestsisabit-maskwhereeachbit-flagrepresentstheemergencyrequesttypethattheclientwishestohandle.SeedefinitionofTEmergencyRequestsfortheemergencyrequesttypesbit-flagpositions.

ThememoryrequirediscalculatedbytheserverandtheTSYaccordingtotheaEmergencyRequestTypeparameter.Ifthepre-allocationofmemorywithinthismethodfails,themethodreturnsKErrNoMemory.Ifthesameemergencyclientcallsthismethodmultipletimes,theETelserverwillreturntheKErrAlreadyExistserror.KErrAlreadyExistswillalsobereturnedifanotherRPhoneclientcreatedusingthesameRTelServersessionalsocallsthismethod.

PleasenotethatETelallocatesemergencyheapperclientormorepreciselyperclient’sRTelServersession.Theclientisexpectedtouseonlyoneemergencysub-sessionofthesametypeatatime.Iftheclienthasarequirementtousemultiple,concurrentsubsessionsthathandlethesameemergencyfunctionality,thenitneedstoopenseparateRTelServersessions,otherwiseETelmightrunoutofthepreallocatedemergencymemory.

ThismethodispolicedwiththeWriteDeviceDatacapability.Multipleclientscancallthismethodaslongastheyhavesufficientplatseccapability.

3.5 RetrieveCapabilityInformation

TIntRPhone::GetCaps(TCaps&aCaps)

ThisfunctionreturnsthephonecapabilitiesintheaCapsvariable.AninstanceoftheTCapstemplatemustbepassedastheaCapsvariable.ThispackagestheTCapsstructure,whichcontainsoneiFlags

variable.

Thepossiblevaluesforthisvariablearedescribedbelow.

3.6 CapabilitiesChangeNotification

TIntRPhone::NotifyCapsChange(TRequestStatus&aStatus,TCaps&aCaps);

Thisfunctioncompleteswhenthedynamiccapabilitiesofthephonechange.SeetheprevioussectionforvaluesthataCapsmaytake.

?NOKIACORPORATIONAND/ORITSSUBSIDIARIES

9

KCapsUnknown

Thecapabilitiesofthephonearenotcurrentlyknown.

KCapsData

Thephonesupportsdatacalls.

KCapsFaxClassOne

Thephonesupportsthefaxclass1interface.

KCapsFaxClassOnePointZero

Thephonesupportsthefaxclass1.0interface.

KCapsFaxClassTwo

Thephonesupportsthefaxclass2interface.

KCapsFaxClassTwoPointZero

Thephonesupportsthefaxclass2.0interface.

KCapsFaxClassTwoPointOne

Thephonesupportsthefaxclass2.1interface.

KCapsVoice

Thephonesupportsvoicecalls.

KCapsEventModemDetection

Thephonesupportsmodemdetectionevents,i.e.itcannotifyclientswhenthemodemcanbeorcannolongerbedetected.

KCapsStealCommPort

Thephonesupportstheabilitytotakethecommsportfromwhatevercomponentiscurrentlyusingit.

NBThisrequiresnewfunctionalitytobeimplementedintheCommsServerwhichisnotthereatpresent;ietheabilityforoneC32clienttosnatchtheownershipofthecommsportfromanotherclient.

Constant Description

ETELCOREAPIDESIGN

INTERNAL

ISSUEDREV1.6

3.7

CancelaCapabilitiesChangeNotification

TIntRPhone::NotifyCapsChangeCancel()const;

Thisfunctioncancelsanoutstandingrequestfornotificationofthecapabilitiesofthephonechanging.

3.8 RetrieveStatusInformation

TIntRPhone::GetStatus(TStatus&aStatus)

Thisfunctionretrievesinformationaboutthestatusofthephone.aStatusstructure,whichisdescribedbelow.

PrimitiveTypes

Thisinformationisreturnedinthe

StructuredTypes:

3.9 EnumerateLines

TIntRPhone::EnumerateLines(TInt&aCount)

ThisfunctionreturnsthenumberoflinesassociatedwiththephoneintheaCountvariable.

3.10RetrieveLineInformation

TIntRPhone::GetLineInfo(TIntaIndex,TLineInfo&aLineInfo)

ThisfunctionreturnsinformationaboutthelinespecifiedbytheaIndexvariable.TheinformationisreturnedintheaLineInfostructure,whichisdescribedbelow.

?NOKIACORPORATIONAND/ORITSSUBSIDIARIES

10

TStatus

iModemDetected

TModemDetection

Thecurrentmodemdetectionstate.TModemDetectionvaluesaredescribedabove

iMode

TMode

Thecurrentmodeofthephone.TModevaluesaredescribedabove.

EDetectedPresent

Thephonehasdetectedthatthelocalmodemispresent.

EDetectedNotPresent

Thephonehasdetectedthatthelocalmodemisnotpresent.

EDetectedUnknown

Thephonehasnotyetdetectedthestatusofthelocalmodem.

TModemDetection

EModeUnknown

Thephoneiscurrentlyinanunknownstate.

EModeIdle

Thephoneiscurrentlyidle

EModeEstablishingLink

Thephoneiscurrentlytryingtoestablishacall.

EModeOnlineData

Thephoneisintheconnectedand“on-linedata“state

EModeOnlineCommand

Thephoneisintheconnectedand“on-linecommand“state

TMode

ETELCOREAPIDESIGN

INTERNAL

ISSUEDREV1.6

3.11ModemDetectionNotification

voidRPhone::NotifyModemDetected(TRequestStatus&aStatus,TModemDetection&aDetection)

Thisfunctionallowsaclienttobenotifiedwhenthelocalmodemisdetectedorwhenapreviouslyconnectedmodemcannolongerbecontacted.Clearly,thisfunctionhasnouseifthemodem(DCE)ispermanentlyattachedtothecomputingdevice(DTE).Ifsupported,therequestwillbecompletedwhenthephone’sconnectionstatuschanges.UponcompletiontheaDetectionvariablewillcontainthenewstatus.ValuesforTModemDetectionaredescribedinsection3.6.

3.12CancelaModemDetectionNotification

voidRPhone::NotifyModemDetectedCancel()

Thisfunctioncancelsanoutstandingmodemdetectionnotification,placedusingtheNotifyModemDetectedfunction.

3.13PhoneClassMemberData

AlltheinformationassociatedwithaninstanceofthecoreGSMAPIphoneclassiscollectedtogetherintoasingle,directlyaccessible,structuretoincreasetheefficiencyofthoseapplicationswhichrequireaccesstothemajorityofthephone’sdata.

ThefollowingtabledescribesthemembervariablesoftheTPhoneInfoclass.

3.13.1GetCurrentPhoneInformation

TIntRPhone::GetInfo(TPhoneInfo&aPhoneInfo)

Thisfunctionretrievesasnapshotofthecurrentphoneinformation,describedinthetableabovee.

3.14CloseaPhone

TIntRPhone::Close()

Thisfunctionclosestheclient-sidehandleonthephone.Ifthisisthelasthandleonthephone,thenitwillalsodeletetheserver-sidephoneobject.

?NOKIACORPORATIONAND/ORITSSUBSIDIARIES

11

iDetection

TModemDetection

Thecurrentmodemdetectionstate.TModemDetectionvaluesaredescribedinsection3.6

TPhoneInfo

iStatus

RCall::TStatus

Thecurrentlinestatus.Thevaluesofthisarethesameasacallstatusandaredescribedinthe“RetrieveCallStatus”section.

iLineCapsFlags

TUint32

Theline’scapabilitiesflags,describedinthe“RetrieveLineCapabilities”section.

iName

TName

Thenameoftheline.

TLineInfo

ETELCOREAPIDESIGN

INTERNAL

ISSUEDREV1.6

4 LineRequests

4.1 OpenaLine

TIntRLine::Open(RPhone&aPhone,constTDesC&aName)

TIntRLine::Open(RTelServer&aServer,constTDesC&aName)

Thesefunctionsopenalinefromaphoneandaserverconnectionrespectively.ThenameofthelineisgivenbytheaNamevariableandmustmatchthenamepassedwiththeGetLineInfofunction.

4.2 RetrieveLineCapabilities

TIntRLine::GetCaps(TCaps&aCaps)

ThisfunctionreturnsthelinecapabilitiesintheaCapsvariable.AninstanceoftheTCapstemplatemustbepassedastheaCapsvariable.ThispackagestheTCapsstructure,whichcontainsoneiFlagsvariable.Thepossiblevaluesforthisvariablearedescribedbelow.

4.3 CapabilitiesChangeNotification

TIntRLine::NotifyCapsChange(TRequestStatus&aStatus,TCaps&aCaps);

Thisfunctioncompleteswhenthedynamiccapabilitiesofthelinechange.SeetheprevioussectionforvaluesthataCapsmaytake.

4.4

CancelaCapabilitiesChangeNotification

TIntRLine::NotifyCapsChangeCancel()const;

Thisfunctioncancelsanoutstandingrequestfornotificationofthecapabilitiesofthelinechanging.

4.5 RetrieveStatusInformation

TIntRLine::GetStatus(TStatus&aStatus)

ThisfunctionreturnslinestatusinformationintheaStatusvariable.Thisvariablemaytakethefollowingvalues.

?NOKIACORPORATIONAND/ORITSSUBSIDIARIES

12

Variable Description

EStatusUnknown

Thelinestatusiscurrentlyunknown.

EStatusIdle

Thelineisidle.

EStatusDialling

Thelineisdialling

EStatusRinging

Thelineisringing.

EStatusAnswering

Thelineisanswering.

EStatusConnecting

Thelineisconnecting.

EStatusConnected

Thelineisconnected.

Constant Description

KCapsData

Thelinesupportsdataconnections.

KCapsFax

Thelinesupportsfaxconnections.

KCapsVoice

Thelinesupportsvoiceconnections.

KCapsEventIncomingCall

Thelinesupportsincomingcallnotificationrequests.

ETELCOREAPIDESIGN

INTERNAL

ISSUEDREV1.6

4.6

RetrieveHookStatus

TIntRLine::GetHookStatus(THookStatus&aHookStatus)

ThisfunctionreturnshookthecurrentstatusintheaHookStatusvariable.Thisvariablemaytakeoneofthefollowingvalues.

4.7 EnumeratingCalls

TIntRLine::EnumerateCall(TInt&aCount)

Thisfunctionreturnsthenumberofcallsopenedfromtheline.ThenumberofcallsisreturnedintheaCountvariable.

4.8 RetrieveCallInformation

TIntRLine::GetCallInfo(TIntaIndex,TCallInfo&aCallInfo)

ThisfunctionreturnsinformationaboutthecallspecifiedbytheaIndexvariable.ThecallinformationisreturnedintheaCallInfostructure,whichisdescribedbelow.

4.9 IncomingCallNotification

voidRLine::NotifyIncomingCall(TRequestStatus&aStatus,TName&aName)

Thisfunctionallowsaclienttobenotifiedwhenanincomingcallisdetected.Thefunctioncompleteswhenanincomingcallisdetectedorwhenacancelofthenotificationisrecognised.ThenameofthecallonwhichAnswerIncomingCall()shouldbeansweredisreturnedintheaNamevariable.

4.10CancelIncomingCallNotification

TIntRLine::NotifyIncomingCallCancel()

Thisfunctionallowsaclienttocancelanoutstandingincomingcallnotification,placedwiththeNotifyIncomingCallrequest.

4.11HookChangeNotification

voidRLine::NotifyHookChange(TRequestStatus&aStatus,THookStatus&aHookStatus)

?NOKIACORPORATIONAND/ORITSSUBSIDIARIES

13

Constant Description

iCallName

Thenameofthecall.

iStatus

Thecallstatus,describedinthe“RetrieveCallStatus”section.

iCallCapsFlags

Thecallcapabilitiesflags,describedinthe“RetrieveCallCapabilities”section.

EHookStatusOff

Thelineiscurrentlyoffhook.

EHookStatusOn

Thelineiscurrentlyonhook.

EHookStatusUnknown

Thestatusoftheline’shookiscurrentlyunknown.

Constant Description

EStatusHangingUp

Thelineishangingup.

Variable Description

ETELCOREAPIDESIGN

INTERNAL

ISSUEDREV1.6

Thisfunctionallowsaclienttobenotifiedwhenthehookchangesstatus.Therequestwillbecompletedwhentheline’shookstatuschanges.UponcompletiontheaHookStatusvariablewillcontainthenewhookstatus.

4.12CancelaHookChangeNotification

voidRLine::NotifyHookChangeCancel()

Thisfunctioncancelsanoutstandinghookchangenotificationrequest,placedusingtheNotifyHookChangefunction.

4.13LineStatusNotification

voidRLine::NotifyStatusChange(TRequestStatus&aStatus,TStatus&aLineStatus)

Thisfunctionnotifiesaclientaboutachangeinthestatusofaline.Therequestwillcompletewhenthelinemodestatuschanges.UponcompletionthenewlinestatuswillbereturnedintheaLineStatusvariable.

4.14CancelLineStatusNotification

voidRLine::NotifyStatusChangeCancel()

Thisfunctioncancelsanoutstandinglinestatuschangenotificationrequest,placedusingtheNotifyStatusChangefunction.

4.15NewCallAddedNotification

voidRLine::NotifyCallAdded(TRequestStatu