CContactMatcher Class Reference
class CContactMatcher : public CBase
|
CContactMatcher
class is an API for contact matching.
Before a method starts executing a Virtual Phonebook operation, it checks if there's an older asynchronous operation already in execution. If there is, synchronous methods leave with error code KErrInUse. Asynchronous methods complete the request with same error code.
If phone backup/restore has been detected, using methods which require Virtual Phonebook is not possible normally. Instead those methods leave with error code KErrAccessDenied. Once EStoreBackupRestoreCompleted event has been received, methods can be called normally.
Public Member Functions
|
|
~CContactMatcher
()
|
IMPORT_C void
|
CancelOperation
()
|
IMPORT_C void
|
CloseStoresL
()
|
IMPORT_C
TInt
|
ContactHasFieldOfTypeL
(
TAiwAddressSelectType
, const
MVPbkStoreContact
&)
|
IMPORT_C MPbk2ContactNameFormatter &
|
ContactNameFormatterL
()
|
IMPORT_C const
MVPbkFieldTypeList
&
|
FieldTypes
()
|
IMPORT_C CVPbkContactManager &
|
GetContactManager
()
|
IMPORT_C
MVPbkContactStoreList
&
|
GetContactStoresL
()
|
IMPORT_C
TPtrC8
|
GetFieldDataBinaryL
(const
MVPbkStoreContact
&, const
MVPbkFieldType
&)
|
IMPORT_C
TTime
|
GetFieldDataDateTimeL
(const
MVPbkStoreContact
&, const
MVPbkFieldType
&)
|
IMPORT_C
TPtrC
|
GetFieldDataTextL
(const
MVPbkStoreContact
&, const
MVPbkFieldType
&)
|
IMPORT_C
HBufC
*
|
GetNameL
(
MVPbkStoreContactFieldCollection
&)
|
IMPORT_C void
|
GetStoreContactL
(const
MVPbkContactLink
&,
MVPbkStoreContact
**)
|
IMPORT_C void
|
GetStoreContactL
(const
MVPbkContactLink
&,
MVPbkStoreContact
**,
TRequestStatus
&)
|
IMPORT_C void
|
IsOwnNumberL
(const
TDesC
&,
TBool
&)
|
IMPORT_C void
|
IsOwnNumberL
(const
TDesC
&,
TRequestStatus
&)
|
IMPORT_C void
|
MatchDataL
(const
TDesC
&, const
MVPbkFieldTypeList
&,
CVPbkContactLinkArray
&)
|
IMPORT_C void
|
MatchDataL
(const
MDesC16Array
&, const
MVPbkFieldTypeList
&,
CVPbkContactLinkArray
&, const
TCallBack
&)
|
IMPORT_C void
|
MatchDataL
(const
TDesC
&, const
MVPbkFieldTypeList
&,
CVPbkContactLinkArray
&,
TRequestStatus
&)
|
IMPORT_C void
|
MatchPhoneNumberL
(const
TDesC
&,
TInt
,
CVPbkPhoneNumberMatchStrategy::TVPbkPhoneNumberMatchFlags
,
CVPbkContactLinkArray
&)
|
IMPORT_C void
|
MatchPhoneNumberL
(const
TDesC
&,
TInt
,
CVPbkPhoneNumberMatchStrategy::TVPbkPhoneNumberMatchFlags
,
CVPbkContactLinkArray
&,
TRequestStatus
&)
|
IMPORT_C
CContactMatcher
*
|
NewL
(
RFs
*)
|
IMPORT_C
CContactMatcher
*
|
NewLC
(
RFs
*)
|
IMPORT_C void
|
OpenAllStoresL
()
|
IMPORT_C void
|
OpenAllStoresL
(
TRequestStatus
&)
|
IMPORT_C void
|
OpenDefaultMatchStoresL
()
|
IMPORT_C void
|
OpenDefaultMatchStoresL
(
TRequestStatus
&)
|
IMPORT_C void
|
OpenOwnNumberStoresL
()
|
IMPORT_C void
|
OpenOwnNumberStoresL
(
TRequestStatus
&)
|
IMPORT_C void
|
OpenStoreL
(const
CVPbkContactStoreUriArray
&)
|
IMPORT_C void
|
OpenStoreL
(const
CVPbkContactStoreUriArray
&,
TRequestStatus
&)
|
Private Member Functions
|
|
CContactMatcher
(
RFs
*)
|
void
|
CleanupNumberMatch
()
|
void
|
ConstructL
()
|
void
|
CopyFindResultsL
(
MVPbkContactLinkArray
*)
|
MVPbkContactFieldSelector *
|
CreateFieldTypeSelectorLC
(
TInt
)
|
void
|
FindCompleteL
(
MVPbkContactLinkArray
*)
|
void
|
FindFailed
(
TInt
)
|
const
MVPbkStoreContactField
*
|
FindField
(const
MVPbkStoreContact
&, const
MVPbkFieldType
&)
|
void
|
FindFromStoreFailed
(
MVPbkContactStore
&,
TInt
)
|
void
|
FindFromStoreSucceededL
(
MVPbkContactStore
&,
MVPbkContactLinkArray
*)
|
void
|
FindFromStoresOperationComplete
()
|
void
|
FreeOldOperation
()
|
CVPbkContactStoreUriArray
*
|
GetStoreArrayLC
(const
TDesC
&(*[])())
|
void
|
HandleStoreEventL
(
MVPbkContactStore
&,
TVPbkContactStoreEvent
)
|
void
|
InitOperation
(
TRequestStatus
*)
|
void
|
InitOperationL
(
TMethodId
)
|
void
|
InitOperationL
(
TMethodId
,
TRequestStatus
*)
|
void
|
MatchPhoneNumberCommonL
(const
TDesC
&,
TInt
,
CVPbkPhoneNumberMatchStrategy::TVPbkPhoneNumberMatchFlags
)
|
void
|
OpenComplete
()
|
void
|
OpenStoreCommonL
(const
CVPbkContactStoreUriArray
&)
|
void
|
OpenStoreL
(const
TDesC
&(*[])())
|
void
|
OpenStoreL
(const
TDesC
&(*[])(),
TRequestStatus
&)
|
void
|
OperationComplete
(
TInt
)
|
void
|
OperationFailed
(
TInt
)
|
void
|
RemoveSimilarEmailAddressesL
(const
TDesC
&,
CVPbkContactLinkArray
&, const
MVPbkFieldTypeList
&)
|
void
|
StoreReady
(
MVPbkContactStore
&)
|
void
|
StoreUnavailable
(
MVPbkContactStore
&,
TInt
)
|
void
|
VPbkSingleContactOperationComplete
(MVPbkContactOperationBase &,
MVPbkStoreContact
*)
|
void
|
VPbkSingleContactOperationFailed
(MVPbkContactOperationBase &,
TInt
)
|
Constructor & Destructor Documentation
CContactMatcher(RFs *)
CContactMatcher
|
(
|
RFs
*
|
aFsSession
|
)
|
[private]
|
~CContactMatcher()
IMPORT_C
|
~CContactMatcher
|
(
|
)
|
|
Member Functions Documentation
CancelOperation()
IMPORT_C void
|
CancelOperation
|
(
|
)
|
|
Cancels asynchronous operation.
CleanupNumberMatch()
void
|
CleanupNumberMatch
|
(
|
)
|
[private]
|
CloseStoresL()
IMPORT_C void
|
CloseStoresL
|
(
|
)
|
|
Closes all currently open contact stores including OwnNumber stores.
ConstructL()
void
|
ConstructL
|
(
|
)
|
[private]
|
ContactHasFieldOfTypeL(TAiwAddressSelectType, const MVPbkStoreContact &)
Finds out if the contact has the right field, support for phonenumber, email and mms
ContactNameFormatterL()
IMPORT_C MPbk2ContactNameFormatter &
|
ContactNameFormatterL
|
(
|
)
|
|
Returns reference to the contact name formatter. Object is created if not used earlier.
CopyFindResultsL(MVPbkContactLinkArray *)
CreateFieldTypeSelectorLC(TInt)
MVPbkContactFieldSelector *
|
CreateFieldTypeSelectorLC
|
(
|
TInt
|
aResId
|
)
|
[private]
|
FieldTypes()
Returns the global list of possible field types.
FindCompleteL(MVPbkContactLinkArray *)
Called when find is complete. Callee takes ownership of the results. In case of an error during find, the aResults may contain only partial results of the find.
Parameters
MVPbkContactLinkArray
* aResults
|
Array of contact links that matched the find. Callee must take ownership of this object in the end of the function, ie. in case the function does not leave.
|
FindFailed(TInt)
void
|
FindFailed
|
(
|
TInt
|
aError
|
)
|
[private]
|
Called in case the find fails for some reason.
Parameters
TInt
aError
|
One of the system wide error codes.
|
FindField(const MVPbkStoreContact &, const MVPbkFieldType &)
FindFromStoreFailed(MVPbkContactStore &, TInt)
This function is called if/when there were errors while searching from a store.
FindFromStoreSucceededL(MVPbkContactStore &, MVPbkContactLinkArray *)
Called when find is complete on a single store. Callee takes ownership of the results. In case of an error during find, the aResultsFromStore may contain only partial results of the find.
Parameters
MVPbkContactStore
& aStore
|
is the store from which the contacts were searched from
|
MVPbkContactLinkArray
* aResultsFromStore
|
Array of contact links that matched the find. Callee must take ownership of this object in the end of the function, ie. in case the function does not leave.
|
FindFromStoresOperationComplete()
void
|
FindFromStoresOperationComplete
|
(
|
)
|
[private]
|
Called when find is complete.
FreeOldOperation()
void
|
FreeOldOperation
|
(
|
)
|
[private]
|
GetContactManager()
IMPORT_C CVPbkContactManager &
|
GetContactManager
|
(
|
)
|
|
Returns reference to the contactmanager
GetContactStoresL()
Returns the used contact store list, needed for e.g. aiw fetch
GetFieldDataBinaryL(const MVPbkStoreContact &, const MVPbkFieldType &)
Returns a pointer to contact's field data of given field type. If the field type isn't found from contact, return value is KNullDesC8. NOTE: this works only for field types of storage type EVPbkFieldStorageTypeBinary. For other types, leaves with error code KErrArgument.
GetFieldDataDateTimeL(const MVPbkStoreContact &, const MVPbkFieldType &)
Returns a pointer to contact's field data of given field type. If the field type isn't found from contact, return value is "1.1.1111". (d.m.yyyy). NOTE: this works only for field types of storage type EVPbkFieldStorageTypeDateTime. For other types, leaves with error code KErrArgument.
GetFieldDataTextL(const MVPbkStoreContact &, const MVPbkFieldType &)
Returns a pointer to contact's field data of given field type. If the field type isn't found from contact, return value is KNullDesC. NOTE: this works only for field types of storage type EVPbkFieldStorageTypeText. For other types, leaves with error code KErrArgument.
GetNameL(MVPbkStoreContactFieldCollection &)
Returns the name of the contact in the same format as MPbk2ContactNameFormatter
GetStoreArrayLC(const TDesC &(*[])())
Parameters
const
TDesC
&(*[])() aFuncPtrs
|
|
GetStoreContactL(const MVPbkContactLink &, MVPbkStoreContact **)
Gets a store contact from a contact link.
Parameters
const
MVPbkContactLink
& aContactLink
|
The link from which store contact should be returned.
|
MVPbkStoreContact
** aStoreContact
|
Pointer to store contact. Client must take the ownership immediately.
|
GetStoreContactL(const MVPbkContactLink &, MVPbkStoreContact **, TRequestStatus &)
Gets a store contact from a contact link. Asynchronous version. Parameters like in the synchronous version, but status code is returned in aStatus.
HandleStoreEventL(MVPbkContactStore &, TVPbkContactStoreEvent)
InitOperation(TRequestStatus *)
InitOperationL(TMethodId)
void
|
InitOperationL
|
(
|
TMethodId
|
aApiMethod
|
)
|
[private]
|
InitOperationL(TMethodId, TRequestStatus *)
IsOwnNumberL(const TDesC &, TBool &)
IMPORT_C void
|
IsOwnNumberL
|
(
|
const
TDesC
&
|
aSearch,
|
|
TBool
&
|
aResult
|
|
)
|
|
Determines whether a phone number is OwnNumber. Synchronous version. The method searches for the number from currently open stores. In order to use SIM's ISDN store, it should be the only open store. Can be opened with
OpenOwnNumberStoresL()
.
Parameters
const
TDesC
& aSearch
|
Phone number to search for
|
TBool
& aResult
|
Boolean result.
|
IsOwnNumberL(const TDesC &, TRequestStatus &)
Determines whether a phone number is OwnNumber. Asynchronous version. The method searches for the number from currently open stores. In order to use SIM's ISDN store, it should be the only open store. Can be opened with
OpenOwnNumberStoresL()
.
Parameters
const
TDesC
& aSearch
|
Phone number to search for
|
TRequestStatus
& aStatus
|
Request status containing the result and possible error code. KErrNone = TRUE, KErrNotFound = FALSE, other value = system wide error code.
|
MatchDataL(const TDesC &, const MVPbkFieldTypeList &, CVPbkContactLinkArray &)
Finds contacts with field data that match the search string. Contacts are searched from all currently open contact stores. Matching is done from field types given by the method caller. The list of all possible field types can be fetched from the wrapper using
FieldTypes()
.
Parameters
const
TDesC
& aSearch
|
Search string
|
const
MVPbkFieldTypeList
& aFieldTypes
|
List of field types included in matching.
|
CVPbkContactLinkArray
& aLinkArray
|
Links to matching contacts are returned in this array that method caller provides.
|
MatchDataL(const MDesC16Array &, const MVPbkFieldTypeList &, CVPbkContactLinkArray &, const TCallBack &)
Finds contacts with field data that match the search string. Contacts are searched from all currently open contact stores. Matching is done from field types given by the method caller. The list of all possible field types can be fetched from the wrapper using
FieldTypes()
.
Parameters
const
MDesC16Array
& aSearchStrings
|
Search strings
|
const
MVPbkFieldTypeList
& aFieldTypes
|
List of field types included in matching.
|
CVPbkContactLinkArray
& aLinkArray
|
Links to matching contacts are returned in this array that method caller provides.
|
const
TCallBack
& aWordParserCallBack
|
is the callback function to the parser
|
MatchDataL(const TDesC &, const MVPbkFieldTypeList &, CVPbkContactLinkArray &, TRequestStatus &)
Finds contacts with field data that match the search string. Asynchronous version. Searching is done according to parameters like in the synchronous version, but status code is returned in aStatus.
MatchPhoneNumberCommonL(const TDesC &, TInt, CVPbkPhoneNumberMatchStrategy::TVPbkPhoneNumberMatchFlags)
MatchPhoneNumberL(const TDesC &, TInt, CVPbkPhoneNumberMatchStrategy::TVPbkPhoneNumberMatchFlags, CVPbkContactLinkArray &)
Finds contacts with phone numbers that match the search string. Synchronous version. Contacts are searched from all currently open contact stores. Matching is done from the end of the phone number. Note: If the search string is shorter than 7 digits, matching from Phone memory contact store works ONLY if the phone number is exactly the same as the search string. Example: Search string "567" would find phone number "567", but not "1234567". From SIM stores both numbers would be found.
MatchPhoneNumberL(const TDesC &, TInt, CVPbkPhoneNumberMatchStrategy::TVPbkPhoneNumberMatchFlags, CVPbkContactLinkArray &, TRequestStatus &)
Finds contacts with phone numbers that match the search string. Asynchronous version. Searching is done according to parameters like in the synchronous version, but status code is returned in aStatus.
NewL(RFs *)
Parameters
RFs
* aFsSession
|
File server session.
|
NewLC(RFs *)
Two-phase constructor for
CContactMatcher
class. Like
NewL()
, but also places instance on cleanup stack.
OpenAllStoresL()
IMPORT_C void
|
OpenAllStoresL
|
(
|
)
|
|
Opens all contact stores for future match operations. NOTE: does not open OwnNumber store.
-
Exceptions
-
KErrNotSupported
|
when none of the stores opens
|
KErrGeneral
|
if some stores are already open
|
OpenAllStoresL(TRequestStatus &)
Opens all contact stores for future match operations. Asynchronous version. NOTE: does not open OwnNumber store.
Parameters
TRequestStatus
& aStatus
|
Completion status of the request. KErrNone - at least one store opened successfully KErrNotSupported - all stores failed to open KErrGeneral - if some stores are already open
|
OpenComplete()
void
|
OpenComplete
|
(
|
)
|
[private]
|
Called when the opening process is complete, ie. all stores have been reported either failed or successfully opened.
OpenDefaultMatchStoresL()
IMPORT_C void
|
OpenDefaultMatchStoresL
|
(
|
)
|
|
Opens default contact stores for future match operations. Used to find local aliases to phone numbers and email addresses NOTE: does not open OwnNumber store or fixed dialing store Opens the stores in the default preference order
-
Exceptions
-
KErrNotSupported
|
when none of the stores opens
|
KErrGeneral
|
if some stores are already open
|
OpenDefaultMatchStoresL(TRequestStatus &)
Opens default contact stores for future match operations. Used to find local aliases to phone numbers and email addresses Asynchronous version. NOTE: does not open OwnNumber store or fixed dialing store Opens the stores in the default preference order
Parameters
TRequestStatus
& aStatus
|
Completion status of the request. KErrNone - at least one store opened successfully KErrNotSupported - all stores failed to open KErrGeneral - if some stores are already open
|
OpenOwnNumberStoresL()
IMPORT_C void
|
OpenOwnNumberStoresL
|
(
|
)
|
|
Opens all OwnNumber stores for future match operations.
-
Exceptions
-
KErrNotSupported
|
when none of the stores opens
|
KErrGeneral
|
if some stores are already open
|
OpenOwnNumberStoresL(TRequestStatus &)
Opens all OwnNumber stores for future match operations.
Parameters
TRequestStatus
& aStatus
|
Completion status of the request. KErrNone - at least one store opened successfully KErrNotSupported - all stores failed to open KErrGeneral - if some stores are already open
|
OpenStoreCommonL(const CVPbkContactStoreUriArray &)
OpenStoreL(const CVPbkContactStoreUriArray &)
Opens one or more contact stores for future match operations.
-
Exceptions
-
KErrNotSupported
|
when none of the stores opens
|
KErrGeneral
|
if some stores are already open
|
OpenStoreL(const CVPbkContactStoreUriArray &, TRequestStatus &)
Opens one or more contact stores for future match operations. Asynchronous version.
Parameters
const
CVPbkContactStoreUriArray
& aUriArray
|
Array of contact store URIs to be opened.
|
TRequestStatus
& aStatus
|
Completion status of the request. KErrNone - at least one store opened successfully KErrNotSupported - all stores failed to open KErrGeneral - if some stores are already open
|
OpenStoreL(const TDesC &(*[])())
void
|
OpenStoreL
|
(
|
const
TDesC
&(*[])()
|
aFuncPtrs
|
)
|
[private]
|
Parameters
const
TDesC
&(*[])() aFuncPtrs
|
|
OpenStoreL(const TDesC &(*[])(), TRequestStatus &)
OperationComplete(TInt)
void
|
OperationComplete
|
(
|
TInt
|
ErrorCode =
KErrNone
|
)
|
[private]
|
OperationFailed(TInt)
void
|
OperationFailed
|
(
|
TInt
|
aError
|
)
|
[private]
|
RemoveSimilarEmailAddressesL(const TDesC &, CVPbkContactLinkArray &, const MVPbkFieldTypeList &)
StoreReady(MVPbkContactStore &)
Called when a contact store is ready for use.
StoreUnavailable(MVPbkContactStore &, TInt)
Called when a contact store becomes unavailable. Client may inspect the reason of the unavailability and decide whether or not it will keep the store opened (ie. listen to the store events).
Parameters
MVPbkContactStore
& aContactStore
|
The store that became unavailable.
|
TInt
aReason
|
The reason why the store is unavailable. This is one of the system wide error codes.
|
VPbkSingleContactOperationComplete(MVPbkContactOperationBase &, MVPbkStoreContact *)
void
|
VPbkSingleContactOperationComplete
|
(
|
MVPbkContactOperationBase &
|
aOperation,
|
|
MVPbkStoreContact
*
|
aContact
|
|
)
|
[private]
|
Called when operation is completed.
Parameters
MVPbkContactOperationBase & aOperation
|
the completed operation.
|
MVPbkStoreContact
* aContact
|
the contact returned by the operation. Client must take the ownership immediately.
|
VPbkSingleContactOperationFailed(MVPbkContactOperationBase &, TInt)
void
|
VPbkSingleContactOperationFailed
|
(
|
MVPbkContactOperationBase &
|
aOperation,
|
|
TInt
|
aError
|
|
)
|
[private]
|
Called if the operation fails.
Parameters
MVPbkContactOperationBase & aOperation
|
the failed operation.
|
TInt
aError
|
error code of the failure.
|
Member Enumerations Documentation
Enum TMethodId
Enumerators
ENoMethod = 0
|
|
EMatchPhoneNumber
|
|
EMatchData
|
|
EGetStoreContact
|
|
EOpenStore
|
|
ECloseStores
|
|
Enum TMethodStatus
Enumerators
EIdle = 0
|
|
EExecuting
|
|
EFinished
|
|
Member Data Documentation
CActiveSchedulerWait
iASchedulerWait
TMethodStatus
iApiMethodStatus
TRequestStatus * iClientStatus
CVPbkContactManager * iContactManager
CVPbkContactManager *
|
iContactManager
|
[private]
|
RFs * iFsSession
RFs
*
|
iFsSession
|
[private]
|
CVPbkPhoneNumberMatchStrategy * iMatchStrategy
MPbk2ContactNameFormatter * iNameFormatter
MPbk2ContactNameFormatter *
|
iNameFormatter
|
[private]
|
MVPbkContactOperationBase * iOperation
MVPbkContactOperationBase *
|
iOperation
|
[private]
|
RResourceFile
iResourceFile
TBool
iResourceFileInitialized
TBool
|
iResourceFileInitialized
|
[private]
|
CVPbkContactLinkArray * iResultContactLinkArray
TInt
iResultContactLinkCnt
TInt
|
iResultContactLinkCnt
|
[private]
|
MVPbkStoreContact ** iResultStoreContact
CPbk2SortOrderManager * iSortOrderManager
CPbk2SortOrderManager *
|
iSortOrderManager
|
[private]
|
CVPbkContactStoreUriArray * iStoreUris
CVPbkPhoneNumberMatchStrategy::TConfig * iStratConfig
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights
reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License
v1.0.