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.