1 // Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // Phonebook Synchroniser API Client side implementation. This file implements

    15 // the methods used to package the client data and pass it to the front-end server

    16 // for processing.

    17 // 

    18 //

    19 

    20 /**

    21  @file

    22  @publishedAll

    23  @released

    24 */

    25 

    26 #include "phbksync.h"

    27 #include "common.h"

    28 #include "Phonebook.h"

    29 #include "PhonebookManager.h"

    30 #include "SyncContactICCEntry.h"

    31 #include "phbksyncsvr.h"

    32 #include "phbksynclog.h"

    33 

    34 

    35 /**

    36  *  Phonebook Synchroniser API version.

    37  */

    38 const TInt  KPhonebookSyncMajorVersion = 1;

    39 const TInt  KPhonebookSyncMinorVersion = 2;

    40 const TInt  KPhonebookSyncBuildVersion = 1;

    41 

    42 

    43 /**

    44  *  Holds any client data that is used in RPhoneBookSession requests. Typically

    45  *  this is data for asynchronous requests which need to be repackaged. This is

    46  *  currently just the RPhoneBookSession::WriteContact() APIs.

    47  *

    48  *  Its data used in an asyncronous request, that does not fit into a IPC

    49  *  request. E.g. It is bigger that the 4 32-bit numbers, and is not a

    50  *  descriptor. It must be put in a descriptor before it can be sent, and

    51  *  that memory has to be allocated somewhere on the client side. 

    52  *

    53  *  The API code also uses this class to ensure BC by keeping the size of R-classes

    54  *  constant. Future data can be added to this class as required.

    55  */

    56 class CSyncClientData : public CBase

    57 	{

    58 public:

    59 	static CSyncClientData* NewL();

    60 	void ConstructL();

    61 	CSyncClientData();

    62 	~CSyncClientData();

    63 

    64 public:

    65     //

    66     // The following fields allow a contact mapped in internal format and other

    67     // data related to the WriteContact() API call to be streamed across the IPC

    68     // boundary.

    69     //

    70 	RPhoneBookSession::TTemplateAndBufferSize  iWrtCntTmpltIdAndBufSize;

    71 	CSyncContactICCEntry*  iWrtCntEntry;

    72 	CBufBase*  iWrtCntEntryBuf;

    73 	TUid  iWrtCntDefaultPhbkUid;

    74 	TPtrC8  iWrtCntTmpltIdAndBufSizePtr;

    75 	TPtr8  iWrtCntSlotNumPtr;

    76 	TPtr8  iWrtCntPhBkIDPtr;

    77 	TPtr8  iWrtCntEntryBufPtr;

    78 	};

    79 

    80 

    81 /**

    82  *  Start the server process which lives in its own executable and rendezvous with it.

    83  *

    84  *  @return  KErrNone if successful, or an error code if not.

    85  */

    86 static TInt StartPhBkSyncServer()

    87 	{

    88 	LOGCLIENT1(_L8("StartPhBkSyncServer()"));

    89 	

    90 	//

    91 	// Create a new server process. Simultaneous launching of two such

    92 	// processes should be detected when the second one attempts to

    93 	// create the server object, failing with KErrAlreadyExists.

    94 	//		

    95 	_LIT(KPhBkSyncSvrExeImg, "PHBKSYNCSVREXE.EXE");

    96 	RProcess server;

    97 	

    98 	TInt  ret = server.Create(KPhBkSyncSvrExeImg, KNullDesC);

    99 	if (ret != KErrNone)

   100 		{

   101 		return ret;

   102 		}

   103 	

   104 	//

   105 	// Rendezvous with the server or abort startup...

   106 	//

   107 	TRequestStatus  status;

   108 

   109 	server.Rendezvous(status);

   110 	if (status != KRequestPending)

   111 		{

   112 		server.Kill(0);

   113 		}

   114 	else

   115 		{

   116 		server.Resume();

   117 		}

   118 	User::WaitForRequest(status);

   119 

   120 	//

   121 	// We can't use the 'exit reason' if the server paniked as this

   122 	// is the panic 'reason' and may be '0' which cannot be distinguished

   123 	// from KErrNone.

   124 	//

   125 	if (server.ExitType() == EExitPanic)

   126 		{

   127 		ret = KErrGeneral;

   128 		}

   129 	else

   130 		{

   131 		ret = status.Int();

   132 		}

   133 

   134 	server.Close();

   135 

   136 	return ret;

   137 	} // StartPhBkSyncServer

   138 

   139 

   140 /**

   141  *  Standard constructor.

   142  */

   143 EXPORT_C RPhoneBookSession::RPhoneBookSession()

   144   : iData(NULL)

   145 	{

   146 	// NOP

   147 	} // RPhoneBookSession::RPhoneBookSession

   148 

   149 

   150 /**

   151  *  Connects the client to the Phonebook Synchroniser Server. 

   152  *

   153  *  This must be used before any of the other methods listed in this API

   154  *  section. The first client to call this method will cause the initiation of

   155  *  the Phonebook Synchroniser Server within its own executable process.

   156  *

   157  *  @return  KErrNone if successful, a system-wide error code if not. 

   158  *

   159  *  @capability None

   160  */

   161 EXPORT_C TInt RPhoneBookSession::Connect()

   162 	{

   163 	LOGCLIENT1(_L8("RPhoneBookSession::Connect()"));

   164 	

   165 	__ASSERT_ALWAYS(iData == NULL,

   166 					PhBkSyncPanic(EPhBkSyncPanicHandleNotClosed));

   167 

   168 	//

   169 	// Create a session with the server, but if it doesn't exist then start it and

   170 	// then create a session.

   171 	//

   172 	TInt  result = CreateSession(PHBKSYNC_SERVER_NAME,

   173 								 TVersion(KPhonebookSyncMajorVersion,

   174 	                					  KPhonebookSyncMinorVersion,

   175 	                					  KPhonebookSyncBuildVersion));

   176 	if (result == KErrNotFound  ||  result == KErrServerTerminated)

   177 		{

   178 		result = StartPhBkSyncServer();

   179 		

   180 		if(result == KErrNone)

   181 			{

   182 			result = CreateSession(PHBKSYNC_SERVER_NAME,

   183 								   TVersion(KPhonebookSyncMajorVersion,

   184 	                					    KPhonebookSyncMinorVersion,

   185 	                					    KPhonebookSyncBuildVersion));

   186 			}

   187 		}	

   188 		

   189 	if (result == KErrNone)

   190 		{

   191 		TRAP(result, iData = CSyncClientData::NewL());

   192 		}

   193 

   194 	//

   195 	// If the creation of the session fails clean up session data...

   196 	//

   197 	if (result != KErrNone)

   198 		{

   199 		Close();

   200 		}

   201 

   202 	return result;

   203 	} // RPhoneBookSession::Connect

   204 

   205 

   206 /**

   207  *  Closes the client's session with the Phonebook Synchroniser Server. 

   208  *

   209  *  @capability None

   210  */

   211 EXPORT_C void RPhoneBookSession::Close()

   212 	{

   213 	LOGCLIENT1(_L8("RPhoneBookSession::Close()"));

   214 

   215 	RSessionBase::Close();

   216 

   217 	delete iData;

   218 	iData = NULL;

   219 	} // RPhoneBookSession::Close

   220 

   221 

   222 /**

   223  *  Returns the current version of the Phonebook Synchroniser Server.

   224  *

   225  *  @return The version of the Phonebook Synchroniser Server. 

   226  *

   227  *  @capability None

   228  */

   229 EXPORT_C TVersion RPhoneBookSession::Version() const

   230 	{

   231 	LOGCLIENT1(_L8("RPhoneBookSession::Version()"));

   232 

   233 	return(TVersion(KPhonebookSyncMajorVersion,

   234 	                KPhonebookSyncMinorVersion,

   235 	                KPhonebookSyncBuildVersion));

   236 	} // RPhoneBookSession::Version

   237 

   238 

   239 /**

   240  *  Requests the shutdown of the server when the last client disconnects.

   241  *  There is no support for immediate shutdown functionality. This API call

   242  *  can only be executed if the server is compiled as a debug release.

   243  *  

   244  *  @param aConditional  If true, subsequent connection requests from any client

   245  *                       will be honoured delaying shutdown until they disconnect.

   246  *                       If untrue, all subsequent connect requests will be denied.

   247  *

   248  *  @return  KErrNone if successful, a system-wide error code if not. 

   249  *

   250  *  @capability ReadUserData

   251  *  @capability WriteUserData 

   252  */

   253 EXPORT_C TInt RPhoneBookSession::ShutdownServer(TBool aConditional)

   254 	{	

   255 	LOGCLIENT1(_L8("RPhoneBookSession::ShutdownServer()"));

   256 

   257 	return SendReceive(ESyncShutdownServer, TIpcArgs(aConditional));

   258 	} // RPhoneBookSession::ShutdownServer

   259 

   260 

   261 /**

   262  *  Executes a manual synchronisation of the Global/GSM ADN phonebook entries.

   263  *

   264  *  @param aReqStatus  On completion, KErrNone if successful, a system-wide error 

   265  *                     code if not. 

   266  *

   267  *  @capability ReadUserData

   268  *  @capability WriteUserData

   269  */

   270 EXPORT_C void RPhoneBookSession::DoSynchronisation(TRequestStatus& aReqStatus)

   271 	{

   272 	DoSynchronisation(aReqStatus, KUidIccGlobalAdnPhonebook);

   273 	} // RPhoneBookSession::DoSynchronisation

   274 

   275 

   276 /**

   277  *  Instructs the Phonebook Synchroniser Server to start a manual synchronisation

   278  *  of the ICC phonebook specified by the aPhonebook parameter.

   279  *

   280  *  @param aReqStatus     On completion, KErrNone if successful, a system-wide

   281  *						  error code if not. 

   282  *  @param aPhonebookUid  TUid of the ICC phonebook to be synchronised.

   283  *

   284  *  @capability ReadUserData

   285  *  @capability WriteUserData

   286  */

   287 EXPORT_C void RPhoneBookSession::DoSynchronisation(TRequestStatus& aReqStatus,

   288 												   TUid aPhonebookUid)

   289 	{

   290 	LOGCLIENT1(_L8("RPhoneBookSession::DoSynchronisation"));

   291 	

   292 	SendReceive(ESyncDoSynchronisation, TIpcArgs(aPhonebookUid.iUid), aReqStatus);

   293 	} // RPhoneBookSession::DoSynchronisation

   294 

   295 

   296 /**

   297  *  Instructs the Phonebook Synchroniser Server to verify the access to the ICC

   298  *  contact item stored in the Contacts database. The server is responsible for

   299  *  mapping the UID to the phonebook this item belongs to.

   300  *

   301  *  @param aOperation  Holds the type of check, search, edit, read.

   302  *  @param aId         The contact model UID of the record stored in the database.

   303  *

   304  *  @return KErrNone if operation was successful, otherwise return error

   305  *

   306  *  @capability ReadUserData

   307  */

   308 EXPORT_C TInt RPhoneBookSession::ValidateContact(MContactSynchroniser::TValidateOperation aOperation, 

   309 												 TContactItemId aId)

   310 	{

   311 	LOGCLIENT1(_L8("RPhoneBookSession::ValidateContact"));

   312 

   313 	return SendReceive(ESyncValidateContact, TIpcArgs(aId, aOperation));

   314 	} // RPhoneBookSession::ValidateContact

   315 

   316 

   317 /**

   318  *  Writes the contact item to the Global/GSM ADN phonebook. This can be used

   319  *  to edit an existing contact or to create a new contact.

   320  *

   321  *  @param aReqStatus    On completion, KErrNone if successful, a system-wide error 

   322  *                       code if not.

   323  *  @param aContactItem  The contact item to write to the ICC card.

   324  *  @param aSlotNumber   The slot number to write to contact into. If set to

   325  *                       KSyncIndexNotSupplied the Phonebook Synchroniser Server

   326  *                       will use the first empty slot and aSlotNumber will contain

   327  *                       the slot number used on completion.

   328  *

   329  *  @capability WriteUserData

   330  */

   331 EXPORT_C void RPhoneBookSession::WriteContact(TRequestStatus& aReqStatus,

   332                                               CContactICCEntry& aContactItem, 

   333 											  TInt& aSlotNumber)

   334 	{

   335 	__ASSERT_ALWAYS(iData != NULL,

   336 					PhBkSyncPanic(EPhBkSyncPanicNullHandle));

   337 

   338 	//

   339 	// The dummy phonebook ID value is used as we are the old API and must communicate

   340 	// the ADN ID to the server. However the server may write it back and thus it must

   341 	// be a valid memory address after this function finishes (which is before the async

   342 	// request will complete).

   343 	//

   344 	iData->iWrtCntDefaultPhbkUid = KUidIccGlobalAdnPhonebook;

   345 	

   346 	WriteContact(aReqStatus, aContactItem, aSlotNumber,

   347 	             iData->iWrtCntDefaultPhbkUid);

   348 	} // RPhoneBookSession::WriteContact

   349 	

   350 

   351 /**

   352  *  Write the contact item supplied in the aContactItem parameter to the ICC

   353  *  phonebook specified by aPhonebookUid.

   354  *

   355  *  This method is used to edit an existing or write new entry to the ICC phonebook.

   356  *  When editing an existing entry the slot number will be supplied in aContactItem,

   357  *  whereas for new entries the new slot number will be returned in the aSlotNumber

   358  *  parameter. Similarly for new entries the phonebook UID will be returned in the

   359  *  aPhonebookUid parameter.

   360  *

   361  *  @param aReqStatus     On completion, KErrNone if successful, a system-wide error 

   362  *                        code if not.

   363  *  @param aContactItem   Contacts ICC entry.

   364  *  @param aPhonebookUid  UID of the ICC phonebook.

   365  *  @param aSlotNumber    Allocated slot number.

   366  *

   367  *  @capability WriteUserData

   368  */

   369 EXPORT_C void RPhoneBookSession::WriteContact(TRequestStatus& aReqStatus, CContactICCEntry& aContactItem, 

   370 											  TInt& aSlotNumber, TUid& aPhonebookUid)

   371 	{

   372 	LOGCLIENT1(_L8("RPhoneBookSession::WriteContact()"));

   373 

   374 	//

   375 	// Check that the sync client data is available and free any previous

   376 	// buffer.

   377 	//

   378 	__ASSERT_ALWAYS(iData != NULL,

   379 					PhBkSyncPanic(EPhBkSyncPanicNullHandle));

   380 

   381 	//

   382 	// Convert the entry to internal format used by PhBkSync. This is needed

   383 	// as use of a Contact Database entry can be dependant on a transaction

   384 	// being open, therefore an independent structure is used. Also a

   385 	// CContactICCEntry is not streamable whereas the internal format is.

   386 	//

   387 	TRAPD(err, iData->iWrtCntEntry->InitialiseFromContactICCEntryL(aContactItem));

   388 	if (err != KErrNone)

   389 		{

   390 		TRequestStatus*  status = &aReqStatus; 

   391 		User::RequestComplete(status, err);

   392 		return;

   393 		}

   394 

   395 	if (aSlotNumber != KSyncIndexNotSupplied)

   396 		{

   397 		iData->iWrtCntEntry->iSlotNum = aSlotNumber;

   398 		}

   399 

   400 #ifdef _DEBUG

   401 	iData->iWrtCntEntry->LogSyncContactICCEntry();

   402 #endif

   403 

   404 	//

   405 	// Stream the entry into a single buffer. This will allow the entry to be

   406 	// read accoss the IPC boundary.

   407 	//

   408 	// Note: The iWrtCntEntryBuf buffer is allocated by StoreL().

   409 	//

   410 	if (iData->iWrtCntEntryBuf)

   411 		{

   412 		delete iData->iWrtCntEntryBuf;  

   413 		iData->iWrtCntEntryBuf = NULL;

   414 		}

   415 

   416 	TRAP(err, iData->iWrtCntEntryBuf = iData->iWrtCntEntry->StoreL());

   417 	if (err != KErrNone)

   418 		{

   419 		TRequestStatus*  status = &aReqStatus; 

   420 		User::RequestComplete(status, err);

   421 		return;

   422 		}

   423 

   424 	//

   425 	// Setup the pointers for the transfer of the contact across the IPC

   426 	// boundary.

   427 	//

   428 	iData->iWrtCntTmpltIdAndBufSize.bufferSize = iData->iWrtCntEntryBuf->Size();

   429 	iData->iWrtCntTmpltIdAndBufSize.templateId = iData->iWrtCntEntry->iTemplateId;

   430 

   431 	iData->iWrtCntTmpltIdAndBufSizePtr.Set(reinterpret_cast<const TText8*>(&iData->iWrtCntTmpltIdAndBufSize),

   432 										   sizeof(RPhoneBookSession::TTemplateAndBufferSize));

   433 	iData->iWrtCntSlotNumPtr.Set(reinterpret_cast<TText8*>(&aSlotNumber),

   434 								 sizeof(aSlotNumber), sizeof(aSlotNumber));

   435 	iData->iWrtCntPhBkIDPtr.Set(reinterpret_cast<TText8*>(&aPhonebookUid),

   436 								sizeof(aPhonebookUid), sizeof(aPhonebookUid));

   437 	iData->iWrtCntEntryBufPtr.Set(iData->iWrtCntEntryBuf->Ptr(0));

   438 

   439 	TIpcArgs  args(&iData->iWrtCntTmpltIdAndBufSizePtr,

   440 	               &iData->iWrtCntSlotNumPtr,

   441 	               &iData->iWrtCntPhBkIDPtr,

   442 	               &iData->iWrtCntEntryBufPtr);

   443 

   444 	SendReceive(ESyncWriteCntToICC, args, aReqStatus);

   445 

   446 	//

   447 	// This function uses the session client data space to store encoded

   448 	// parameters before they are sent to the front-end server.  This means

   449 	// that there is a small risk that if another call to WriteContact is made

   450 	// before this one completes, then the data maybe corrupted.

   451 	//

   452 	// To prevent this we issue a synchronous request here. This will ensure

   453 	// that at a minimum the request is read by the server and pre-processed

   454 	// such that the data and pointer locations are read and stored inside the

   455 	// server.

   456 	//

   457 	// This leaves only a risk that if the requests are ADN single phonebook

   458 	// API versions, then the dummy Phonebook ID may be overwritten. This is

   459 	// of course not a problem as the dummy value is not used.

   460 	//

   461 	SendReceive(ESyncFlushInterfaceQueue, TIpcArgs());

   462 	} // RPhoneBookSession::WriteContact

   463 

   464 

   465 /**

   466  *  Deletes the contact item from the ICC card.

   467  *

   468  *  @param aReqStatus  On completion, KErrNone if successful, a system-wide error 

   469  *                     code if not.

   470  *  @param aId         The contact item to delete. 

   471  *

   472  *  @capability WriteUserData

   473  */

   474 EXPORT_C void RPhoneBookSession::DeleteContact(TRequestStatus& aReqStatus, TContactItemId aId)

   475 	{

   476 	LOGCLIENT1(_L8("RPhoneBookSession::DeleteContact()"));

   477 

   478 	SendReceive(ESyncDeleteCntFromICC, TIpcArgs(aId), aReqStatus);

   479 	} // RPhoneBookSession::DeleteContact

   480 

   481 

   482 /**

   483  *  Returns information about the supported fields within an ICC phonebook entry. 

   484  *

   485  *  The TContactFieldFormat type defines the information available for each field 

   486  *  and TContactFieldsV1 is a collection of this information for all supported 

   487  *  field types. The client can use the field information to tailor its UI so 

   488  *  that user can only enter fields with the maximum number of supported characters.

   489  *

   490  *  The only fields supported by GSM ADN phonebook are the name, number and ICC 

   491  *  slot number, so these are the only fields included in TContactFieldsV1.

   492  *

   493  *  TContactFieldsV2 is used to contain the new USIM phonebook fields.

   494  *

   495  *  TContactFieldsV3 is an extension of TContactFieldsV2 and contains additional

   496  *  information on the fields supported by the USIM phonebooks.

   497  *

   498  *  @param aContactFields  On return, the packaged TContactFieldsV1/V2/V3

   499  *                         is filled with the supported field information.

   500  *

   501  *  @return KErrNone if successful, a system-wide error code if not. 

   502  *

   503  *  @capability None

   504  */

   505 EXPORT_C TInt RPhoneBookSession::GetContactFormat(TDes8& aContactFields)

   506 	{

   507 	LOGCLIENT1(_L8("RPhoneBookSession::GetContactFormat()"));

   508 

   509 	TUid  phonebook(KUidIccPhonebookNotSpecified);

   510 

   511 	TContactFieldsV1Pckg*  contactFieldsV1Pckg = static_cast<TContactFieldsV1Pckg*>(&aContactFields);

   512 	TContactFieldsV1&  contactFieldsV1 = (*contactFieldsV1Pckg)();

   513 	TContactFieldsV1::TContactFieldsExtensionId  extensionId = static_cast<TContactFieldsV1::TContactFieldsExtensionId>(contactFieldsV1.ExtensionId());

   514 	

   515 	if (extensionId == TContactFieldsV1::KPhBkSyncTContactFieldsV2)

   516 		{

   517 		TContactFieldsV2Pckg*  contactFieldsV2Pckg = static_cast<TContactFieldsV2Pckg*>(&aContactFields);

   518 		TContactFieldsV2&  contactFieldsV2 = (*contactFieldsV2Pckg)();

   519 		phonebook = contactFieldsV2.iPhonebook;

   520 		}

   521 	else if (extensionId == TContactFieldsV1::KPhBkSyncTContactFieldsV3)

   522 		{

   523 		TContactFieldsV3Pckg*  contactFieldsV3Pckg = static_cast<TContactFieldsV3Pckg*>(&aContactFields);

   524 		TContactFieldsV3&  contactFieldsV3 = (*contactFieldsV3Pckg)();

   525 		phonebook = contactFieldsV3.iPhonebook;

   526 		}

   527 	else

   528 		{

   529 		//

   530 		// Phonebook for TContactFieldsV1 is set to Global ADN, as the same

   531 		// information is set for all phonebooks.

   532 		//

   533 		phonebook = KUidIccGlobalAdnPhonebook;

   534 		}

   535 

   536 	return SendReceive(ESyncGetContactFormat, TIpcArgs(phonebook.iUid, extensionId, 

   537 	                                                   &aContactFields)); 

   538 	} // RPhoneBookSession::GetContactFormat

   539 

   540 

   541 /**

   542  *  Returns the current setting for the synchronisation mode of the Global/GSM ADN

   543  *  phonebook, used by the Phonebook Synchroniser Server at start-up to determine

   544  *  if the phonebook should be automatically synchronised.

   545  *

   546  *  @param aSyncMode  On return, the synchronisation mode.

   547  *

   548  *  @return KErrNone if the setting is successfully returned in aSyncMode, or

   549  *          an error code if the setting does not exist or can not be accessed. 

   550  *

   551  *  @capability None

   552  */

   553 EXPORT_C TInt RPhoneBookSession::GetSyncMode(TPhonebookSyncMode& aSyncMode)

   554 	{

   555 	return GetSyncMode(aSyncMode, KUidIccGlobalAdnPhonebook);

   556 	} // RPhoneBookSession::GetSyncMode

   557 

   558 

   559 /**

   560  *  Returns the current setting for the Synchonisation Mode of the ICC phonebook

   561  *  specified by aPhonebookUid and used by the Phonebook Synchroniser Server at

   562  *  start-up to determine if the phonebook should be automatically synchronised.

   563  *

   564  *  @param aSyncMode      On return Will contain the current synchronisation mode.

   565  *  @param aPhonebookUid  TUid of the ICC phonebook

   566  *

   567  *  @return KErrNone if operation was successful, otherwise return error.

   568  *

   569  *  @capability None

   570  */

   571 EXPORT_C TInt RPhoneBookSession::GetSyncMode(TPhonebookSyncMode& aSyncMode,

   572                                              TUid aPhonebookUid)

   573 	{

   574 	LOGCLIENT1(_L8("RPhoneBookSession::GetSyncMode()"));

   575 

   576 	TPckg<TPhonebookSyncMode>  syncModePtr(aSyncMode);

   577 

   578 	return SendReceive(ESyncGetSyncMode, TIpcArgs(aPhonebookUid.iUid, &syncModePtr));

   579 	} // RPhoneBookSession::GetSyncMode

   580 

   581 

   582 /**

   583  *  Sets a new value for the synchronisation mode of the Global/GSM ADN phonebook, 

   584  *  used by the Phonebook Synchroniser Server at start-up to determine its

   585  *  synchronisation policy.

   586  *

   587  *  If the mode is changing to EAutoCurrentIcc and no sync has yet been performed,

   588  *  then an automatic sync will be performed.

   589  *

   590  *  @param aSyncMode  The new synchronisation mode.

   591  *

   592  *  @return KErrNone if the setting specified by aSyncMode is successfully changed, 

   593  *          or an error code if the setting does not exist or can not be accessed.

   594  *

   595  *  @capability None

   596  */

   597 EXPORT_C TInt RPhoneBookSession::SetSyncMode(TPhonebookSyncMode aSyncMode)

   598 	{

   599 	return SetSyncMode(aSyncMode, KUidIccGlobalAdnPhonebook);

   600 	} // RPhoneBookSession::SetSyncMode

   601 

   602 

   603 /**

   604  *  Set a new value for the Synchonisation Mode of the ICC phonebook specified by aPhonebookUid,

   605  *  used by the Phonebook Synchroniser Server at start-up to determine its synchronisation 

   606  *  policy.

   607  *

   608  *  @param aSyncMode      Current synchronisation mode

   609  *  @param aPhonebookUid  TUid of the ICC phonebook

   610  *

   611  *  @return KErrNone if operation was successful, otherwise return error

   612  *

   613  *  @capability None

   614  */

   615 EXPORT_C TInt RPhoneBookSession::SetSyncMode(TPhonebookSyncMode aSyncMode,

   616                                              TUid aPhonebookUid)

   617 	{

   618 	LOGCLIENT1(_L8("RPhoneBookSession::SetSyncMode()"));

   619 	

   620 	return SendReceive(ESyncSetSyncMode, TIpcArgs(aPhonebookUid.iUid,aSyncMode));

   621 	} // RPhoneBookSession::SetSyncMode

   622 

   623 

   624 /**

   625  *  Returns the requested UID for the ID type belonging to the Global/GSM ADN

   626  *  phonebook. This is the ID type spedified by aIdType, which can be either the

   627  *  template ID or the group ID for an ICC entry belonging to the Global/GSM ADN

   628  *  phonebook, depending on the type supplied by aIdType.

   629  *

   630  *  @param aId      On return, the contact ID.

   631  *  @param aIdType  The type of ID requested.

   632  *

   633  *  @return KErrNone, if the UID is successfully returned or an error code if the 

   634  *          UID does not exist or can not be accessed. 

   635  *

   636  *  @capability None

   637  */

   638 EXPORT_C TInt RPhoneBookSession::GetPhoneBookId(TContactItemId& aId, TSyncIdType aIdType)

   639 	{

   640 	return GetPhoneBookId(aId, aIdType, KUidIccGlobalAdnPhonebook);

   641 	} // RPhoneBookSession::GetPhoneBookId

   642 

   643 

   644 /**

   645  *  Return either the current group or template ID (depending on the type supplied

   646  *  by aIdType) for the ICC entries belonging to the ICC phonebook specified by the

   647  *  aPhonebookUid parameter.

   648  *

   649  *  @param aId            Contacts UID

   650  *  @param aPhonebookUid  TUid of the ICC phonebook

   651  *  @param aIdType        Type of Contacts UID

   652  *

   653  *  @return  KErrNone if successful, a system-wide error code if not. 

   654  *

   655  *  @capability None

   656  */

   657 EXPORT_C TInt RPhoneBookSession::GetPhoneBookId(TContactItemId& aId, TSyncIdType aIdType,

   658 											    TUid aPhonebookUid)

   659 	{

   660 	LOGCLIENT1(_L8("RPhoneBookSession::GetPhoneBookId()"));

   661 

   662 	TPckg<TContactItemId>  contactItemIdPtr(aId);

   663 

   664 	return SendReceive(ESyncGetPhoneBookId,

   665 	                   TIpcArgs(aPhonebookUid.iUid, aIdType, &contactItemIdPtr));

   666 	} // RPhoneBookSession::GetPhoneBookId

   667 

   668 

   669 /**

   670  *  Updates the Phonebook Synchroniser's look-up table with the new contact ID in

   671  *  the Global/GSM ADN phonebook.

   672  *

   673  *  This function should be called when a new entry has been added to the Contacts

   674  *  Database by a client other than the Phonebook Synchroniser Server, so the server

   675  *  can know what the UID of the newly added contact was.

   676  *

   677  *  The Phonebook Synchroniser plug-in should extract the appropriate details from

   678  *  the item (e.g. item UID and slot number) and call the Phonebook server to update

   679  *  the look-up tables.

   680  *

   681  *  @param aNewUid   The contact use for the update.

   682  *  @param aIccSlot  The ICC slot number to match the Contacts UID.

   683  *

   684  *  @return KErrNone if the look-up table update succeeded, or an error code (such 

   685  *          as KErrArgument) if the operation failed for that ICC slot number. 

   686  *

   687  *  @capability None

   688  */

   689 EXPORT_C TInt RPhoneBookSession::UpdateLookuptable(TContactItemId aNewUid, TInt aIccSlot)

   690 	{

   691 	return UpdateLookuptable(aNewUid, aIccSlot, KUidIccGlobalAdnPhonebook);

   692 	} // RPhoneBookSession::UpdateLookuptable

   693 

   694 

   695 /**

   696  *  Updates the Phonebook Synchroniser's look-up table with the new contact ID in

   697  *  the ICC phonebook specified by the aPhonebookUid parameter

   698  *

   699  *  This function should be called when a new entry has been added to the Contacts

   700  *  Database by a client other than the Phonebook Synchroniser Server, so the server

   701  *  can know what the UID of the newly added contact was.

   702  *

   703  *  The Phonebook Synchroniser plug-in should extract the appropriate details from

   704  *  the item (e.g. item UID and slot number) and call the Phonebook server to update

   705  *  the look-up tables.

   706  *

   707  *  @param aNewUid        Contact UID number unique per entry

   708  *  @param aIccSlot       ICC slot value

   709  *  @param aPhonebookUid  Type of ICC phonebook

   710  *

   711  *  @return KErrNone if operation was successful, otherwise return error

   712  *

   713  *  @capability None

   714  */

   715 EXPORT_C TInt RPhoneBookSession::UpdateLookuptable(TContactItemId aNewUid, TInt aIccSlot,

   716 												   TUid aPhonebookUid)

   717 	{

   718 	LOGCLIENT1(_L8("RPhoneBookSession::UpdateLookuptable()"));

   719 

   720 	return SendReceive(ESyncUpdateLookupTable,

   721 	                   TIpcArgs(aPhonebookUid.iUid, aNewUid, aIccSlot));

   722 	} // RPhoneBookSession::UpdateLookuptable

   723 

   724 

   725 /**

   726  *  Returns the current state of the Phonebook Synchroniser server cache for

   727  *  the Global/GSM ADN phonebook.

   728  *

   729  * @param aState  On return, the state of the phonebook synchroniser cache.

   730  *

   731  * @return KErrNone if the state is successfully retrieved, or an error code if 

   732  *         the server is unable to process the request. 

   733  *

   734  * @capability None

   735  */

   736 EXPORT_C TInt RPhoneBookSession::GetPhoneBookCacheState(TSyncState& aState)

   737 	{

   738 	return GetPhoneBookCacheState(aState, KUidIccGlobalAdnPhonebook);

   739 	} // RPhoneBookSession::GetPhoneBookCacheState

   740 

   741 

   742 /**

   743  *  Return the current phonebook server cache state for the ICC phonebook

   744  *  specified by the aPhonebook parameter.

   745  *

   746  *  @param aState         Current state of the phonebook cache

   747  *  @param aPhonebookUid  Type of ICC phonebook

   748  *

   749  *  @return  KErrNone if successful, a system-wide error code if not. 

   750  *

   751  *  @capability None

   752  */

   753 EXPORT_C TInt RPhoneBookSession::GetPhoneBookCacheState(TSyncState& aState,

   754 														TUid aPhonebookUid)

   755 	{

   756 	LOGCLIENT1(_L8("RPhoneBookSession::GetPhoneBookCacheState()"));

   757 

   758 	TPckg<TSyncState>  statePtr(aState);

   759 	

   760 	return SendReceive(ESyncGetCacheState, TIpcArgs(aPhonebookUid.iUid, &statePtr));

   761 	} // RPhoneBookSession::GetPhoneBookCacheState

   762 

   763 

   764 /**

   765  *  Cancels a previously issued asynchronous request on the Global/GSM ADN phonebook. 

   766  *

   767  *  @param aReqToCancel  The request to be cancelled.

   768  *

   769  *  @capability None

   770  */

   771 EXPORT_C void RPhoneBookSession::CancelRequest(TPhonebookSyncRequestCancel aReqToCancel)

   772 	{

   773 	CancelRequest(aReqToCancel, KUidIccGlobalAdnPhonebook);

   774 	} // RPhoneBookSession::CancelRequest

   775 

   776 

   777 /**

   778  *  Cancels a previously issued asynchronous request. The request to be cancelled

   779  *  is specified by the aReqToCancel parameter and the ICC phonebook for which the

   780  *  request needs to be cancelled is specified by the aPhonebookUid parameter.

   781  *

   782  *  @param aReqToCancel   Request to be cancelled.

   783  *  @param aPhonebookUid  UID of the ICC phonebook.

   784  *

   785  *  @capability ReadUserData

   786  *  @capability WriteUserData

   787  */

   788 EXPORT_C void RPhoneBookSession::CancelRequest(TPhonebookSyncRequestCancel aReqToCancel,

   789 											   TUid aPhonebookUid)

   790 	{

   791 	LOGCLIENT1(_L8("RPhoneBookSession::CancelRequest()"));

   792 

   793 	switch (aReqToCancel)

   794 		{

   795 		case EDoSynchronisationCancelClient:

   796 			{

   797 			SendReceive(ESyncDoSynchronisationCancel, TIpcArgs(aPhonebookUid.iUid));

   798 			}

   799 			break;

   800 

   801 		case ESyncDeleteCntFromICCCancelClient:

   802 			{

   803 			SendReceive(ESyncDeleteCntFromICCCancel, TIpcArgs(aPhonebookUid.iUid));

   804 			}

   805 			break;

   806 

   807 		case ESyncWriteCntToICCCancelClient:

   808 			{

   809 			SendReceive(ESyncWriteCntToICCCancel, TIpcArgs(aPhonebookUid.iUid));

   810 			}

   811 			break;

   812 

   813 		case ESyncNotifyCacheStateChangeCancelClient:

   814 			{

   815 			SendReceive(ESyncNotifyCacheStateChangeCancel, TIpcArgs(aPhonebookUid.iUid));

   816 			}

   817 			break;

   818 

   819 		default:

   820 			{

   821 			PhBkSyncPanic(EPhBkSyncPanicCancelSyncReqError);

   822 			}

   823 			break;

   824 		}

   825 	} // RPhoneBookSession::CancelRequest

   826 

   827 

   828 /**

   829  *  Returns the last server cache sync error for the Global/GSM ADN phonebook. 

   830  *

   831  *  @param aError  Last server cache sync error

   832  *

   833  *  @return  KErrNone if successful, a system-wide error code if not. 

   834  *

   835  *  @capability None

   836  */

   837 EXPORT_C TInt RPhoneBookSession::GetLastSyncError(TInt& aError)

   838 	{

   839 	return GetLastSyncError(aError, KUidIccGlobalAdnPhonebook);

   840 	} // RPhoneBookSession::GetLastSyncError

   841 

   842 

   843 /**

   844  *  Return the last server cache sync error for the requested phonebook.

   845  *

   846  *  @param aError         Last server cache sync error.

   847  *  @param aPhonebookUid  UID of the ICC phonebook.

   848  *

   849  *  @return  KErrNone if successful, a system-wide error code if not. 

   850  *

   851  *  @capability None

   852  */

   853 EXPORT_C TInt RPhoneBookSession::GetLastSyncError(TInt& aError,

   854 												  TUid aPhonebookUid)

   855 	{

   856 	LOGCLIENT1(_L8("RPhoneBookSession::GetLastSyncError()"));

   857 

   858 	TPckg<TInt>  errorPtr(aError);

   859 

   860 	return SendReceive(ESyncGetLastSyncError,

   861 	                   TIpcArgs(aPhonebookUid.iUid, &errorPtr));

   862 	} // RPhoneBookSession::GetLastSyncError

   863 

   864 

   865 /**

   866  *  Registers the notification for a change in the Global/GSM ADN phonebook cache

   867  *  state.

   868  *

   869  *  @note The client should call GetPhoneBookCacheState() in order to get the new 

   870  *        state of the synchroniser.

   871  *

   872  *  @param aReqStatus  On completion, KErrNone if successful, a system-wide error 

   873  *                     code if not.

   874  *

   875  *  @capability None

   876  */

   877 EXPORT_C void RPhoneBookSession::NotifyPhBkCacheStateChange(TRequestStatus& aReqStatus)

   878 	{

   879 	NotifyPhBkCacheStateChange(aReqStatus, KUidIccGlobalAdnPhonebook);

   880 	} // RPhoneBookSession::NotifyPhBkCacheStateChange

   881 

   882 

   883 /**

   884  *  Registers the notification for a change in the Phone book cache state.

   885  *

   886  *  @note  The client should call GetPhoneBookCacheState() in order to get the new 

   887  *  state of the synchroniser.

   888  *

   889  *  @param aReqStatus     On completion, KErrNone if successful, a system-wide error 

   890  *                        code if not.

   891  *  @param aPhonebookUid  UID of the ICC phonebook.

   892  *

   893  *  @capability None

   894  */

   895 EXPORT_C void RPhoneBookSession::NotifyPhBkCacheStateChange(TRequestStatus& aReqStatus,

   896                                                             TUid aPhonebookUid)

   897 	{

   898 	LOGCLIENT1(_L8("RPhoneBookSession::NotifyPhBkCacheStateChange()"));

   899 

   900 	SendReceive(ESyncNotifyCacheStateChange, TIpcArgs(aPhonebookUid.iUid), aReqStatus);

   901 	} // RPhoneBookSession::NotifyPhBkCacheStateChange

   902 

   903 

   904 /**

   905  *  Gets the total number of slots on the Global/GSM ADN phonebook.

   906  *

   907  *  @param aNumSlots  The number of slots.

   908  *

   909  *  @return  KErrNone if successful, a system-wide error code if not. 

   910  *

   911  *  @capability None

   912  */

   913 EXPORT_C TInt RPhoneBookSession::GetNumSlots(TInt& aNumSlots) const

   914     {

   915 	return GetNumSlots(aNumSlots, KUidIccGlobalAdnPhonebook);

   916 	} // RPhoneBookSession::GetNumSlots

   917 

   918 

   919 /**

   920  *  Gets the total number of slots on the specified ICC phonebook.

   921  *

   922  *  @param aNumSlots      The number of slots.

   923  *  @param aPhonebookUid  Type of ICC phonebook

   924  *

   925  *  @return  KErrNone if successful, a system-wide error code if not. 

   926  *

   927  *  @capability None

   928  */

   929 EXPORT_C TInt RPhoneBookSession::GetNumSlots(TInt& aNumSlots,

   930 											 TUid aPhonebookUid) const

   931     {

   932 	LOGCLIENT1(_L8("RPhoneBookSession::GetNumSlots()"));

   933 

   934 	TPckg<TInt>  numSlotsPtr(aNumSlots);

   935 

   936 	return SendReceive(ESyncGetNumSlots, TIpcArgs(aPhonebookUid.iUid, &numSlotsPtr));

   937 	} // RPhoneBookSession::GetNumSlots

   938 

   939 

   940 /**

   941  *  Get the slots that are free in the Global/GSM ADN phonebook.

   942  *

   943  *  @param aFreeSlots  On return, an array of slots numbers that are free.

   944  *

   945  *  @capability None

   946  */

   947 EXPORT_C void RPhoneBookSession::GetFreeSlotsL(RArray<TInt>& aFreeSlots) const

   948 	{

   949 	GetFreeSlotsL(aFreeSlots, KUidIccGlobalAdnPhonebook);

   950 	} // RPhoneBookSession::GetFreeSlotsL

   951 

   952 

   953 /**

   954  *  Get the slots that are free in the requested phonebook.

   955  *

   956  *  @param aFreeSlots     On return, an array of slots numbers that are free.

   957  *  @param aPhonebookUid  Type of ICC phonebook

   958  *

   959  *  @capability None

   960  */

   961 EXPORT_C void RPhoneBookSession::GetFreeSlotsL(RArray<TInt>& aFreeSlots,

   962 											   TUid aPhonebookUid) const

   963 	{

   964 	LOGCLIENT1(_L8("RPhoneBookSession::GetFreeSlotsL"));

   965 

   966 	aFreeSlots.Reset();

   967 

   968 	//

   969 	// Get the number of free slots available...

   970 	//

   971 	TInt  numFreeSlots;

   972 	TPckg<TInt>  numFreeSlotsPtr(numFreeSlots);

   973 	

   974 	TIpcArgs args(aPhonebookUid.iUid,&numFreeSlotsPtr);

   975 	User::LeaveIfError(SendReceive(ESyncGetNumFreeSlots,

   976 	                               TIpcArgs(aPhonebookUid.iUid, &numFreeSlotsPtr)));

   977 

   978 	//

   979 	// Now read back the data about each slot...

   980 	//

   981 	HBufC8*  buf = HBufC8::NewLC(sizeof(TInt) * numFreeSlots);

   982 	TPtr8  bufPtr(buf->Des());

   983 	

   984 	User::LeaveIfError(SendReceive(ESyncGetFreeSlots,

   985 	                               TIpcArgs(aPhonebookUid.iUid, &bufPtr)));

   986 

   987 	RDesReadStream  readStream(*buf);

   988 	CleanupClosePushL(readStream);

   989 	

   990 	for (TInt slot =0;  slot < numFreeSlots;  slot++)

   991 		{

   992 		User::LeaveIfError(aFreeSlots.Append(readStream.ReadInt32L()));

   993 		}

   994 

   995 	CleanupStack::PopAndDestroy(2, buf); // readStream, buf

   996 	} // RPhoneBookSession::GetFreeSlotsL

   997 

   998 

   999 /**

  1000  *  Get the Contacts UID of a particular slot in the Global/GSM ADN phonebook.

  1001  *

  1002  *  @param aSlot  The slot number on which the request is made.

  1003  *  @param aId    The contact Id of the slot number.

  1004  *

  1005  *  @return KErrNotFound if the UID is not found.

  1006  *

  1007  *  @capability None

  1008  */

  1009 EXPORT_C TInt RPhoneBookSession::GetSlotId(TInt aSlot, TContactItemId& aId) const

  1010 	{

  1011 	return GetSlotId(aSlot, aId, KUidIccGlobalAdnPhonebook);

  1012 	} // RPhoneBookSession::GetSlotId

  1013 

  1014 

  1015 /**

  1016  *  Get the Contacts UID of a particular slot in the requested phonebook.

  1017  *

  1018  *  @param aSlot          The slot number on which the request is made.

  1019  *  @param aId            The contact Id of the slot number.

  1020  *  @param aPhonebookUid  Type of ICC phonebook

  1021  *

  1022  *  @return KErrNotFound if the UID is not found.

  1023  *

  1024  *  @capability None

  1025  */

  1026 EXPORT_C TInt RPhoneBookSession::GetSlotId(TInt aSlot, TContactItemId& aId,

  1027 										   TUid aPhonebookUid) const

  1028 	{

  1029 	LOGCLIENT1(_L8("RPhoneBookSession::GetSlotId()"));

  1030 	

  1031 	TPckg<TContactItemId>  contactItemPtr(aId);

  1032 	

  1033 	return SendReceive(ESyncGetSlotId,

  1034 	                   TIpcArgs(aPhonebookUid.iUid,aSlot, &contactItemPtr));

  1035 	} // RPhoneBookSession::GetSlotId

  1036 

  1037 

  1038 /**

  1039  *  Set a heap mark in the Phonebook Sync Server and Background Sync Engine

  1040  *  threads.

  1041  *

  1042  *  @capability None

  1043  */

  1044 EXPORT_C TInt RPhoneBookSession::__DbgMarkHeap()

  1045 	{

  1046 	TIpcArgs args(TIpcArgs::ENothing);

  1047 

  1048 	return SendReceive(ESyncDbgMarkHeap, args);

  1049 	} // RPhoneBookSession::__DbgMarkHeap

  1050 

  1051 

  1052 /**

  1053  *  Performs a heap mark check in the Phonebook Sync Server and Background

  1054  *  Sync Engine threads.

  1055  *

  1056  *  @param aCount  The number of heap cells expected to be allocated at

  1057  *                 the current nest level.

  1058  *

  1059  *  @capability None

  1060  */

  1061 EXPORT_C TInt RPhoneBookSession::__DbgCheckHeap(TInt aCount)

  1062 	{

  1063 	TIpcArgs args(aCount);

  1064 

  1065 	return SendReceive(ESyncDbgCheckHeap, args);

  1066 	} // RPhoneBookSession::__DbgCheckHeap

  1067 

  1068 

  1069 /**

  1070  *  Perfom a heap mark end check in the Phonebook Sync Server and Background

  1071  *  Sync Engine threads.

  1072  *

  1073  *  @param aCount  The number of heap cells expected to remain allocated

  1074  *                 at the current nest level.

  1075  *

  1076  *  @capability None

  1077  */

  1078 EXPORT_C TInt RPhoneBookSession::__DbgMarkEnd(TInt aCount)

  1079 	{

  1080 	TIpcArgs args(aCount);

  1081 

  1082 	return SendReceive(ESyncDbgMarkEnd, args);

  1083 	} // RPhoneBookSession::__DbgMarkEnd

  1084 

  1085 

  1086 /**

  1087  *  Set a heap fail next condition in the Phonebook Sync Server and

  1088  *  Background Sync Engine threads.

  1089  *

  1090  *  @param aCount  Determines when the allocation will fail.

  1091  *

  1092  *  @capability None

  1093  */

  1094 EXPORT_C TInt RPhoneBookSession::__DbgFailNext(TInt aCount)

  1095 	{

  1096 	TIpcArgs args(aCount);

  1097 

  1098 	return SendReceive(ESyncDbgFailNext, args);

  1099 	} // RPhoneBookSession::__DbgFailNext

  1100 

  1101 

  1102 /**

  1103  *  This method creates the RPhoneBookSession CPhoneBookSyncData object which is

  1104  *  used to store temporary data required by some asynchonous requests. 

  1105  *

  1106  *  @return Pointer to newly created CPhoneBookSyncData object.

  1107  */

  1108 CSyncClientData* CSyncClientData::NewL()

  1109 	{

  1110 	CSyncClientData*  syncClientData = new (ELeave) CSyncClientData();

  1111 	CleanupStack::PushL(syncClientData);

  1112 	syncClientData->ConstructL();

  1113 	CleanupStack::Pop(syncClientData);

  1114 

  1115 	return syncClientData;

  1116 	} // CSyncClientData::NewL

  1117 

  1118 

  1119 /**

  1120  *  Second phase constructor.

  1121  */

  1122 void CSyncClientData::ConstructL()

  1123 	{

  1124 	iWrtCntEntry = CSyncContactICCEntry::NewL();

  1125 	} // CSyncClientData::ConstructL

  1126 

  1127 

  1128 /**

  1129  *  Default constructor.

  1130  */

  1131 CSyncClientData::CSyncClientData()

  1132   : iWrtCntTmpltIdAndBufSizePtr(NULL, 0),

  1133     iWrtCntSlotNumPtr(NULL, 0),

  1134     iWrtCntPhBkIDPtr(NULL, 0),

  1135     iWrtCntEntryBufPtr(NULL, 0)