Class RApaLsSession

class RApaLsSession : public RSessionBase;

Description

A session with the application architecture server.

The server provides access to a cached list of the applications on the device.

To use this class, clients first need to connect to the server.

Then, one of GetAllApps(), GetEmbeddableApps() or GetFilteredApps() needs to be called. These functions do some initialisation of server data in preparation for returning the application list (which is owned by the server).

Then, GetNextApp() is called in a loop. The first time around, it populates the session's application list and retrieves the first application in the list. Further calls to GetNextApp() retrieve the remaining applications in the list, until RApaLsSession::ENoMoreAppsInList is returned.

The session should be closed when it is no longer needed, before it goes out of scope.

Various functions in RApaLsSession need to access the application list, and may return RApaLsSession::EAppListInvalid to indicate that the function was called before the initial population of the list is complete. If this occurs, you could try again after a short delay.

This class provides many other functions, for instance launching applications, querying application-specific information, recognising data.

Derivation

• RHandleBase - A handle to an object

• RSessionBase - Client-side handle to a session with a server

• RApaLsSession - A session with the application architecture server

Members

Defined in RApaLsSession:
AppCount(), AppForDataType(), AppForDocument(), AppForDocument(), ApplicationLanguage(), CancelListPopulationCompleteObserver(), CancelNotifyOnDataMappingChange(), CancelRecognizeFiles(), Close(), Connect(), CreateDocument(), DeleteDataMapping(), EAppListInvalid, ELaunchNewApp, ENoMoreAppsInList, ESwitchFiles, EmbeddableAppCount(), GetAcceptedConfidence(), GetAllApps(), GetAllApps(), GetAppCapability(), GetAppIcon(), GetAppIcon(), GetAppIcon(), GetAppIcon(), GetAppIconSizes(), GetAppInfo(), GetAppOwnedFiles(), GetAppViewIcon(), GetAppViewIcon(), GetAppViews(), GetDefaultScreenNumber(), GetEmbeddableApps(), GetEmbeddableApps(), GetFilteredApps(), GetFilteredApps(), GetFilteredApps(), GetFilteredApps(), GetMaxDataBufSize(), GetNextApp(), GetNextApp(), GetPreferredBufSize(), GetSupportedDataTypesL(), InsertDataMapping(), InsertDataMappingIfHigher(), IsProgram(), MatchesSecurityPolicy(), NotifyOnDataMappingChange(), NumberOfOwnDefinedIcons(), RApaLsSession(), RApaLsSession_Reserved1(), RApaLsSession_Reserved2(), RecognizeData(), RecognizeData(), RecognizeFilesL(), RecognizeFilesL(), RecognizeFilesL(), RecognizeFilesL(), RecognizeSpecificData(), RecognizeSpecificData(), RegisterListPopulationCompleteObserver(), SetAcceptedConfidence(), SetAppShortCaption(), SetMaxDataBufSize(), StartApp(), StartApp(), StartApp(), StartDocument(), StartDocument(), StartDocument(), StartDocument(), StartDocument(), StartDocument(), TLaunchType, Version(), anonymous

Inherited from RHandleBase:
Attributes(), Duplicate(), FullName(), Handle(), HandleInfo(), Name(), SetHandle(), SetHandleNC(), iHandle

Inherited from RSessionBase:
CreateSession(), EAutoAttach, EExplicitAttach, Open(), Send(), SendReceive(), SetReturnedHandle(), ShareAuto(), ShareProtected(), TAttachMode

See also

• Class Summary

IMPORT_C RApaLsSession();

Description

IMPORT_C TInt Connect();

Description

Connects a client to the application architecture server, creating a session with it.

Return value

TInt KErrNone if successful; otherwise, one of the system-wide error codes.

IMPORT_C TVersion Version() const;

Description

Gets the version of the application architecture server.

Return value

TVersion The version number.

IMPORT_C TInt AppCount(TInt &aCount) const;

Description

Gets the total number of applications.

Control panel applications are excluded.

Parameters

TInt &aCount On return, the total number of applications.

Return value

TInt KErrNone if successful, otherwise one of the system-wide error codes.

IMPORT_C TInt EmbeddableAppCount(TInt &aCount) const;

Description

Gets the total number of embeddable applications.

Control panel applications are excluded.

Parameters

TInt &aCount On return, the total number of embeddable applications.

Return value

TInt KErrNone, if successful, otherwise one of the system-wide error codes.

IMPORT_C TInt GetAllApps() const;

Description

Initialises the process of getting all applications in the cached list.

Control panel applications are excluded.

A call to this function is followed by subsequent and repeated calls to GetNextApp() to retrieve all applications in the cached list.

Return value

TInt KErrNone, if successful, otherwise one of the system-wide error codes.

IMPORT_C TInt GetAllApps(TInt aScreenMode) const;

Description

Initialises the process of getting all applications in the cached list.

Control panel applications are excluded.

A call to this function is followed by subsequent and repeated calls to GetNextApp() to retrieve all applications supporting aScreenMode in the cached list.

Parameters

TInt aScreenMode Only applications which define a view supporting aScreenMode will be returned by subsequent calls to GetNextApp(). If an application does not define views in it's application information file, only screen mode 0 is supported.

Return value

TInt KErrNone, if successful, otherwise one of the system-wide error codes.

IMPORT_C TInt GetEmbeddableApps() const;

Description

Initialises the process of getting all embeddable applications from the cached list.

Control panel applications are excluded.

A call to this function is followed by subsequent and repeated calls to GetNextApp() to retrieve embeddable applications in the cached list.

Only applications which specify KAppEmbeddable or KAppEmbeddableOnly in their application information file will be returned by subsequent calls to GetNextApp().

Return value

TInt KErrNone, if successful, otherwise one of the system-wide error codes.

IMPORT_C TInt GetEmbeddableApps(TInt aScreenMode) const;

Description

Initialises the process of getting embeddable applications from the cached list that support the specified screen mode.

Control panel applications are excluded.

A call to this function is followed by subsequent and repeated calls to GetNextApp() to retrieve embeddable applications in the cached list.

Only applications which specify KAppEmbeddable or KAppEmbeddableOnly in their application information file will be returned by subsequent calls to GetNextApp().

Parameters

TInt aScreenMode Only embeddable applications which define a view supporting aScreenMode will be returned by subsequent calls to GetNextApp(). If an application does not define views in it's application information file, only screen mode 0 is supported.

Return value

TInt KErrNone, if successful, otherwise one of the system-wide error codes.

IMPORT_C TInt GetFilteredApps(const TApaEmbeddabilityFilter &aFilter) const;

Description

Initialises the process of getting all applications matching aFilter in the cached list.

Control panel applications are excluded.

A call to this function is followed by subsequent and repeated calls to GetNextApp() to retrieve all applications matching aFilter in the cached list.

Parameters

const TApaEmbeddabilityFilter &aFilter Defines the filter to be applied to the cached list.

Return value

TInt KErrNone, if successful, otherwise one of the system-wide error codes.

IMPORT_C TInt GetFilteredApps(const TApaEmbeddabilityFilter &aFilter, TInt aScreenMode) const;

Description

Initialises the process of getting all applications matching aFilter in the cached list.

Control panel applications are excluded.

A call to this function is followed by subsequent and repeated calls to GetNextApp() to retrieve all applications matching aFilter in the cached list.

Parameters

const TApaEmbeddabilityFilter &aFilter Defines the filter to be applied to the cached list. TInt aScreenMode Only applications which define a view supporting aScreenMode will be returned by subsequent calls to GetNextApp(). If an application does not define views in it's application information file, only screen mode 0 is supported.

Return value

TInt KErrNone, if successful, otherwise one of the system-wide error codes.

IMPORT_C TInt GetFilteredApps(TUint aCapabilityAttributeMask, TUint aCapabilityAttributeValue) const;

Description

Initialises the process of getting all applications matching the specified application attributes.

A call to this function is followed by subsequent and repeated calls to GetNextApp() to retrieve all applications matching the filter in the cached list.

Attributes are defined by TApaAppCapability::TCapabilityAttribute

Parameters

TUint aCapabilityAttributeMask Specifies the attributes whose values will be used to filter the cached list. If the mask specifies more than one attribute, all associated attribute values must match. TUint aCapabilityAttributeValue Specifies the attribute values for each attribute identified by the mask.

Return value

TInt KErrNone, if successful, otherwise one of the system-wide error codes.

IMPORT_C TInt GetFilteredApps(TUint aCapabilityAttributeMask, TUint aCapabilityAttributeValue, TInt aScreenMode) const;

Description

Initialises the process of getting all applications matching the specified application attributes.

A call to this function is followed by subsequent and repeated calls to GetNextApp() to retrieve all applications matching the filter in the cached list.

Attributes are defined by TApaAppCapability::TCapabilityAttribute

Parameters

TUint aCapabilityAttributeMask Specifies the attributes whose values will be used to filter the cached list. If the mask specifies more than one attribute, all associated attribute values must match. TUint aCapabilityAttributeValue Specifies the attribute values for each attribute identified by the mask. TInt aScreenMode Only applications which define a view supporting aScreenMode will be returned by subsequent calls to GetNextApp(). If an application does not define views in it's application information file, only screen mode 0 is supported.

Return value

TInt KErrNone, if successful, otherwise one of the system-wide error codes.

IMPORT_C TInt GetNextApp(TApaAppInfo &aInfo) const;

Description

Gets information about the next application or embeddable application from the cached list.

A sequence of calls to this function must always be preceded by a call to one of GetAllApps(), GetEmbeddableApps() or GetFilteredApps().

Parameters

TApaAppInfo &aInfo On return, contains application information.

Return value

TInt KErrNone if successful; ENoMoreAppsInList, if there are no more applications in the list; EAppListInvalid if the server's initial population of the list has not completed; otherwise one of the other system wide error codes.

IMPORT_C TInt GetNextApp(TApaAppInfo &aInfo, TInt aScreenMode) const;

Description

Gets information about the next application or embeddable application from the cached list.

A sequence of calls to this function must always be preceded by a call to one of GetAllApps(), GetEmbeddableApps() or GetFilteredApps().

Parameters

TApaAppInfo &aInfo On return, contains application information. TInt aScreenMode This parameter is ignored.

Return value

TInt KErrNone if successful; ENoMoreAppsInList, if there are no more applications in the list; EAppListInvalid if the server's initial population of the list has not completed; otherwise one of the other system wide error codes.

IMPORT_C TInt GetAppInfo(TApaAppInfo &aInfo, TUid aAppUid) const;

Description

Gets information about the application with the specified UID.

Parameters

TApaAppInfo &aInfo On return, contains the application information, if an application with the specified UID is found. If no matching application is found, then this object is not changed. TUid aAppUid The application specific UID.

Return value

TInt KErrNone if successful; KErrNotFound if a matching entry could not be found; otherwise one of the other system wide error codes.

IMPORT_C TInt SetAppShortCaption(const TDesC &aShortCaption, TLanguage aLanguage, TUid aAppUid);

Description

Sets the short caption of the application.

The captions overrides the short caption specified in the localizable resource file for this application.

Parameters

const TDesC &aShortCaption The short caption of the application. The maximum length allowed is KApaMaxAppCaption defined in apadef.h. TLanguage aLanguage The language corresponding to the caption. If this is ELangNone the caption is used for all languages. TUid aAppUid The uid of the application.

Return value

TInt KErrNone if successful, otherwise one of the system wide error codes.

IMPORT_C TInt GetDefaultScreenNumber(TInt &aDefaultScreenNumber, TUid aAppUid) const;

Description

Gets the default screen-number of the application with the specified UID.

Parameters

TInt &aDefaultScreenNumber On return, contains the default screen-number, if an application with the specified UID is found. If no matching application is found, then this object is not changed. TUid aAppUid The application specific UID.

Return value

TInt KErrNone if successful; KErrNotFound if a matching entry could not be found; otherwise one of the other system wide error codes.

IMPORT_C TInt GetAppCapability(TDes8 &aCapabilityBuf, TUid aAppUid) const;

Description

Gets the capabilities of the application with the specified UID.

Parameters

TDes8 &aCapabilityBuf A modifiable descriptor that, on return, contains the application's capability information. The data returned in the descriptor is mapped by the TApaAppCapability class. If no matching application is found, then the content of this descriptor is not changed. TUid aAppUid The application specific UID.

Return value

TInt KErrNone, if successful; KErrNotFound, if no matching entry can be found; otherwise one of the other system wide error codes.

IMPORT_C TInt StartApp(const CApaCommandLine &aCommandLine);

Description

Starts an application defined by the specified command line information.

This is only recommended for non document based applications.

View based applications are usually started by activating a specific view using CCoeAppUi::ActivateViewL. Alternatively, using StartApp() to start a view based application will activate the application's default view.

Parameters

const CApaCommandLine &aCommandLine The command line.

Return value

TInt KErrNone, if successful; KErrNotFound, if the application cannot be found; otherwise one of the other system-wide error codes.

IMPORT_C TInt StartApp(const CApaCommandLine &aCommandLine, TThreadId &aThreadId);

Description

Starts an application defined by the specified command line information.

This is only recommended for non document based applications.

View based applications are usually started by activating a specific view using CCoeAppUi::ActivateViewL. Alternatively, using StartApp() to start a view based application will activate the application's default view.

Parameters

const CApaCommandLine &aCommandLine The command line. TThreadId &aThreadId On return, the id of the main thread started.

Return value

TInt KErrNone, if successful; KErrNotFound, if the application cannot be found; otherwise one of the other system-wide error codes.

IMPORT_C TInt StartApp(const CApaCommandLine &aCommandLine, TThreadId &aThreadId, TRequestStatus *aRequestStatusForRendezvous);

Description

Starts an application defined by the specified command line information.

This is only recommended for non document based applications.

View based applications are usually started by activating a specific view using CCoeAppUi::ActivateViewL. Alternatively, using StartApp() to start a view based application will activate the application's default view.

Parameters

const CApaCommandLine &aCommandLine The command line. TThreadId &aThreadId On return, the id of the main thread started. TRequestStatus *aRequestStatusForRendezvous If not NULL, the asynchronous RProcess::Rendezvous() function is called (being passed this TRequestStatus object) before RProcess::Resume() is called on the new application process.

Return value

TInt KErrNone, if successful; KErrNotFound, if the application cannot be found; otherwise one of the other system-wide error codes.

IMPORT_C TInt RecognizeData(const TDesC &aName, const TDesC8 &aBuffer, TDataRecognitionResult &aDataType) const;

Description

Gets the data (MIME) type for data taken from a file with a specified name.

Parameters

const TDesC &aName The full filename, including drive and path, of the file containing the data. const TDesC8 &aBuffer A buffer containing data taken from the specified file; typically the data is read from the beginning of the file. TDataRecognitionResult &aDataType On return, contains the result of the attempt to recognize data.

Return value

TInt KErrNone, if successful; otherwise one of the other system-wide error codes.

IMPORT_C TInt RecognizeData(const RFile &aFile, TDataRecognitionResult &aDataType) const;

Description

Gets the data (MIME) type for data in a file passed by handle.

Parameters

const RFile &aFile The file containing the data. Before this function can be called, the file server session which owns this file handle must first be marked as shareable by calling RFs::ShareProtected(). TDataRecognitionResult &aDataType On return, contains the result of the attempt to recognize data.

Return value

TInt KErrNone, if successful; otherwise one of the other system-wide error codes.

IMPORT_C TInt RecognizeSpecificData(const TDesC &aName, const TDesC8 &aBuffer, const TDataType &aDataType, TBool &aResult) const;

Description

Tests whether data taken from a named file has the specified data (MIME) type.

Parameters

const TDesC &aName The name of the file containing the data. const TDesC8 &aBuffer A buffer containing data taken from the specified file; typically the data is read from the beginning of the file. const TDataType &aDataType The data (MIME) type. TBool &aResult On return, contains the result of the test.

Return value

TInt KErrNone, if successful; otherwise one of the other system-wide error codes.

IMPORT_C TInt RecognizeSpecificData(const RFile &aFile, const TDataType &aDataType, TBool &aResult) const;

Description

Tests whether data taken from a file passed by handle has the specified data (MIME) type.

Parameters

const RFile &aFile The file containing the data. Before this function can be called, the file server session which owns this file handle must first be marked as shareable by calling RFs::ShareProtected(). const TDataType &aDataType The data (MIME) type. TBool &aResult On return, contains the result of the test.

Return value

TInt KErrNone, if successful; otherwise one of the other system-wide error codes.

IMPORT_C TInt AppForDataType(const TDataType &aDataType, TUid &aAppUid) const;

Description

Gets the UID of an application that can handle the specified data (MIME) type.

If no application can be found, the function returns the UID of the preferred default handler. If none of the default handlers can handle the data type, then a NULL UID is returned.

Parameters

const TDataType &aDataType The data (MIME) type. TUid &aAppUid On return, the UID of the application that can handle the data (MIME) type; this may be NULL.

Return value

TInt KErrNone, if successful; otherwise one of the other system-wide error codes.

IMPORT_C TInt StartDocument(const TDesC &aFileName, TThreadId &aThreadId, TLaunchType aLaunchType=ELaunchNewApp);

Description

Finds and launches an application to handle the document contained in the specified file.

Parameters

const TDesC &aFileName The document name. TThreadId &aThreadId On return, the id of the main thread started. TLaunchType aLaunchType Not used. Reserved for future use.

Return value

TInt KErrNone, if successful; EAppListInvalid, if the server's initial population of the list has not completed; KErrNotFound, if a matching entry could not be found; otherwise one of the other system-wide error codes.

IMPORT_C TInt StartDocument(RFile &aFile, TThreadId &aThreadId, TRequestStatus *aRequestStatusForRendezvous=0);

Description

Finds and launches an application to handle the document contained in the specified file

Parameters

RFile &aFile The file handle. Before this function can be called, the file server session which owns this file handle must first be marked as shareable by calling RFs::ShareProtected(). TThreadId &aThreadId On return, the id of the main thread started. TRequestStatus *aRequestStatusForRendezvous If not NULL, the asynchronous RProcess::Rendezvous() function is called (being passed this TRequestStatus object) before RProcess::Resume() is called on the new application process.

Return value

TInt KErrNone, if successful; KErrNotFound, if no suitable application can be found; otherwise one of the other system-wide error codes.

IMPORT_C TInt StartDocument(const TDesC &aFileName, const TDataType &aDataType, TThreadId &aThreadId, TLaunchType aLaunchType=ELaunchNewApp);

Description

Launches an application that can handle the specified data (MIME) type.

The application handles the document contained in the specified file.

Parameters

const TDesC &aFileName The document name. const TDataType &aDataType The data (MIME) type. TThreadId &aThreadId On return, the id of the main thread started. TLaunchType aLaunchType Not used. Reserved for future use.

Return value

TInt KErrNone, if successful; EAppListInvalid if the server's initial population of the list has not completed; KErrNotFound, if no suitable application can be found; otherwise one of the other system-wide error codes.

IMPORT_C TInt StartDocument(RFile &aFile, const TDataType &aDataType, TThreadId &aThreadId, TRequestStatus *aRequestStatusForRendezvous=0);

Description

Finds and launches an application to handle the document contained in the specified file

Parameters

RFile &aFile The file handle. const TDataType &aDataType The data (MIME) type. TThreadId &aThreadId On return, the id of the main thread started. TRequestStatus *aRequestStatusForRendezvous If not NULL, the asynchronous RProcess::Rendezvous() function is called (being passed this TRequestStatus object) before RProcess::Resume() is called on the new application process.

Return value

TInt KErrNone, if successful; KErrNotFound, if no suitable application can be found; otherwise one of the other system-wide error codes.

IMPORT_C TInt StartDocument(const TDesC &aFileName, TUid aAppUid, TThreadId &aThreadId, TLaunchType aLaunchType=ELaunchNewApp);

Description

Launches the application identified by the specified UID.

The application handles the document contained in the specified file.

Parameters

const TDesC &aFileName The document name. TUid aAppUid The application specific UID. TThreadId &aThreadId On return, the id of the main thread started. TLaunchType aLaunchType Not used. Reserved for future use.

Return value

TInt KErrNone, if successful; EAppListInvalid if the server's initial population of the list has not completed; KErrNotFound, if no suitable application can be found; otherwise one of the other system-wide error codes.

IMPORT_C TInt StartDocument(RFile &aFile, TUid aAppUid, TThreadId &aThreadId, TRequestStatus *aRequestStatusForRendezvous=0);

Description

Finds and launches an application to handle the document contained in the specified file

Parameters

RFile &aFile The file handle. TUid aAppUid The application specific UID. TThreadId &aThreadId On return, the id of the main thread started. TRequestStatus *aRequestStatusForRendezvous If not NULL, the asynchronous RProcess::Rendezvous() function is called (being passed this TRequestStatus object) before RProcess::Resume() is called on the new application process.

Return value

TInt KErrNone, if successful; KErrNotFound, if no suitable application can be found; otherwise one of the other system-wide error codes.

IMPORT_C TInt CreateDocument(const TDesC &aFileName, TUid aAppUid, TThreadId &aThreadId, TLaunchType aLaunchType=ELaunchNewApp);

Description

Launches the application identified by the specified UID and creates a new document.

To create a document file with the passed document name, the application needs to override the 3-parameter overload of ProcessCommandParametersL() to call the 2-parameter overload.

Otherwise, a document will be created with the default document name present in the application resource file. If default document name is empty or not provided, no document is created.

If the application resource file is not present, a document with application caption name is created.

Parameters

const TDesC &aFileName The document name. TUid aAppUid The application specific UID. TThreadId &aThreadId On return, the id of the main thread started. TLaunchType aLaunchType Not used. Reserved for future use.

Return value

TInt KErrNone, if successful; EAppListInvalid if the server's initial population of the list has not completed; KErrNotFound, if no suitable application can be found; otherwise one of the other system-wide error codes.

IMPORT_C TInt GetAppIcon(TUid aAppUid, TInt aSize, CApaMaskedBitmap &aAppBitmap) const;

Description

gets the bitmap handles from the Server, forms these up into a CApaMaskedBitmap

Sets aAppBitmap to be the small, medium or large app icon of the app with uid aAppUid, when aSize=0, 1 or 2 respectively. Panics the caller if a different index is specified. The overload which takes a TSize should be used instead.

Parameters

TUid aAppUid The application specific UID. TInt aSize The required size of the icon. CApaMaskedBitmap &aAppBitmap On return, the application icon.

Return value

TInt KErrNone, if successful; KErrNotFound, if a matching entry could not be found, or no icon equal to or smaller than the specified size can be found; KErrNotSupported, if the application provides icons in non-MBM format, otherwise one of the other system wide error codes.

IMPORT_C TInt AppForDocument(const TDesC &aFileName, TUid &aAppUid, TDataType &aDataType) const;

Description

Gets the data (MIME) type of the data in the specified file and gets the UID of an application that can handle this type.

Parameters

const TDesC &aFileName The name of the file containing the data. TUid &aAppUid On return, the UID of the application that can handle the data (MIME) type; this may be NULL. TDataType &aDataType On return, the data (MIME) type.

Return value

TInt KErrNone, if successful; otherwise one of the other system-wide error codes.

IMPORT_C TInt AppForDocument(const RFile &aFile, TUid &aAppUid, TDataType &aDataType) const;

Description

Gets the data (MIME) type of the data in the specified file and gets the UID of an application that can handle this type.

Parameters

const RFile &aFile The file containing the data. Before this function can be called, the file server session which owns this file handle must first be marked as shareable by calling RFs::ShareProtected(). TUid &aAppUid On return, the UID of the application that can handle the data (MIME) type; this may be NULL. TDataType &aDataType On return, the data (MIME) type.

Return value

TInt KErrNone, if successful; otherwise one of the other system-wide error codes.

IMPORT_C TInt IsProgram(const TDesC &aFileName, TBool &aProgram) const;

Description

Tests whether the file is a native executable (DLL or EXE).

Parameters

const TDesC &aFileName The name of the file containing the data. TBool &aProgram On return, true, if the file contains application code; false, otherwise.

Return value

TInt KErrNone, if successful; otherwise one of the other system-wide error codes.

IMPORT_C TInt GetAcceptedConfidence(TInt &aConfidence) const;

Description

Gets the confidence threshold for successful data recognition.

This is the minimum acceptable confidence level that must be reported by a data recognizer for data to be accepted as of a given type.

Parameters

TInt &aConfidence On return, the confidence threshold.

Return value

TInt KErrNone, if successful; otherwise one of the other system-wide error codes.

Capability:

WriteDeviceData

IMPORT_C TInt SetAcceptedConfidence(TInt aConfidence);

Description

Sets the confidence threshold for successful data recognition.

This is the minimum acceptable confidence level that must be reported by a data recognizer for data to be accepted as of a given type.

Parameters

TInt aConfidence The confidence threshold. Although this is an integer value, data recognizers use the discrete values defined by the CApaDataRecognizerType::TRecognitionConfidence enumeration.

Return value

TInt KErrNone, if successful; otherwise one of the other system-wide error codes.

IMPORT_C TInt GetMaxDataBufSize(TInt &aBufSize) const;

Description

Gets the maximum size of the data that can be read from a file for the purpose of recognizing the data type.

To determine the size of buffer to pass to the 3-parameter overload of RecognizeData() or to the 4-parameter overload of RecognizeSpecificData(), use GetPreferredBufSize() rather than this function.

Parameters

TInt &aBufSize On return, contains the maximum size.

Return value

TInt KErrNone, if successful; otherwise one of the other system-wide error codes.

See also:

• SetMaxDataBufSize()
• GetPreferredBufSize()

IMPORT_C TInt SetMaxDataBufSize(TInt aBufSize);

Description

Sets the maximum size of the data that can be read from a file for the purpose of recognizing the data type.

The value is not used when the client explicitly supplies a buffer, for example in calls to RecognizeData() and RecognizeSpecificData(), but is used in the implementation of functions such as StartDocument() and CreateDocument().

Unless explicitly set, a default value of KApaAppListServMaxBuffer is used.

Parameters

TInt aBufSize The maximum size of data to be read.

Return value

TInt KErrNone, if successful; otherwise one of the other system-wide error codes.

See also:

• CreateDocument()
• StartDocument()
• RecognizeData()
• RecognizeSpecificData()

IMPORT_C TInt GetPreferredBufSize(TInt &aPreferredBufSize) const;

Description

Gets the preferred number of bytes of data to read from a file for the purpose of recognizing the data type.

This should be used to determine the size of buffer to pass to the 3-parameter overload of RecognizeData() or to the 4-parameter overload of RecognizeSpecificData().

Parameters

TInt &aPreferredBufSize On return, contains either the largest buffer size required by any of the currently installed data-recognizers, or the value that would be returned by GetMaxDataBufSize(), whichever is less.

Return value

TInt KErrNone, if successful; otherwise one of the other system-wide error codes.

See also:

• GetMaxDataBufSize()

IMPORT_C TInt GetSupportedDataTypesL(CDataTypeArray &aDataTypes) const;

Description

Gets a list of all supported data (MIME) types.

Parameters

CDataTypeArray &aDataTypes The array of data (MIME) types.

Return value

TInt KErrNone, if successful; otherwise one of the other system-wide error codes.

IMPORT_C TInt GetAppIconSizes(TUid aAppUid, CArrayFixFlat< TSize > &aArrayToFill) const;

Description

Gets the available icon sizes for the application with the specified UID.

Parameters

TUid aAppUid The application specific UID. CArrayFixFlat< TSize > &aArrayToFill On return, the array contains all of the available icon sizes.

Return value

TInt KErrNone, if successful; KErrNotFound, if no matching application can be found; KErrNotSupported, if the application provides icons in non-MBM format; otherwise one of the other system wide error codes.

IMPORT_C TInt GetAppIcon(TUid aAppUid, TSize aSize, CApaMaskedBitmap &aAppBitmap) const;

Description

Gets the nearest matching application icon for the application with the specified UID.

The function gets the icon whose size matches the specified size. If there is no exact match, then the function gets the closest smaller icon.

This function should be used in preference to the TInt GetAppIcon(TUid,TInt,CApaMaskedBitmap&); overload.

Parameters

TUid aAppUid The application specific UID. TSize aSize The required size of the icon. CApaMaskedBitmap &aAppBitmap On return, the application icon.

Return value

TInt KErrNone, if successful; KErrNotFound, if a matching entry could not be found, or no icon equal to or smaller than the specified size can be found; KErrNotSupported, if the application provides icons in non-MBM format; otherwise one of the other system wide error codes.

IMPORT_C TInt GetAppIcon(TUid aAppUid, RFile &aFile) const;

Description

Gets an open shareable read only file handle to the application icon file for the application with the specified UID.

An icon file can only be defined by applications providing an application registration file.

An icon file may be in any graphics format and contain one or more icons.

On entering this function, aFile must be non-open.It is recommended that aFile is pushed onto the cleanup-stack (via CleanupClosePushL()) before this function is called.

Parameters

TUid aAppUid The application specific UID. RFile &aFile On return, a read only open file handle to the icon file.

Return value

TInt KErrNone, if successful; KErrNotFound, if a matching application could not be found, or an icon filename was not defined; otherwise one of the other system wide error codes.

IMPORT_C TInt GetAppViews(CApaAppViewArray &aAppViews, TUid aAppUid) const;

Description

Gets the views published by the application that has the specified UID.

Information on each view is contained in a TApaAppViewInfo object, and this set of objects is put into the array supplied by the caller.

Parameters

CApaAppViewArray &aAppViews On return, the array contains information on all of the views published by the specified application. TUid aAppUid The application specific UID.

Return value

TInt KErrNone, if successful; KErrNotFound, if no matching application can be found; otherwise one of the other system wide error codes.

See also:

• TApaAppViewInfo

IMPORT_C TInt GetAppViewIcon(TUid aAppUid, TUid aViewUid, const TSize &aSize, CApaMaskedBitmap &aViewBitmap) const;

Description

Gets the icon for the specified view published by the application that has the specified UID.

The icon returned is that which is closest in size to the specified size.

Parameters

TUid aAppUid The application specific UID. TUid aViewUid The UID identifying the view. const TSize &aSize The requested size of the icon. CApaMaskedBitmap &aViewBitmap On return, the icon that is closest in size to the requested size.

Return value

TInt KErrNone, if successful; KErrNotFound, if no matching application nor matching view can be found; KErrNotSupported, if the application provides icons in non-MBM format; otherwise one of the other system wide error codes.

IMPORT_C TInt GetAppOwnedFiles(CDesCArray &aAppOwnedFiles, TUid aAppUid) const;

Description

Gets the list of file names for which the application with the specified UID claims ownership.

The list is written to a descriptor array supplied by the caller.

Note that if the function fails due to lack of memory, the array is left in an undefined state.

Parameters

CDesCArray &aAppOwnedFiles On return, the descriptor array contains the file names. TUid aAppUid The application specific UID.

Return value

TInt KErrNone, if successful; KErrNotFound, if no matching application can be found; otherwise one of the other system wide error codes.

IMPORT_C TInt NumberOfOwnDefinedIcons(TUid aAppUid, TInt &aCount) const;

Description

Gets the number of icons defined by the app that has the specified UID

Applications that don't define icons in their application information file will return an aCount value of zero when this function is called.

Parameters

TUid aAppUid The application specific UID TInt &aCount On return, contains the number of icons defined by the application

Return value

TInt KErrNone, if successful; KErrNotFound, if a matching application could not be found; KErrNotSupported, if the application provides icons in non-MBM format; otherwise one of the other system-wide error codes.

IMPORT_C TInt GetAppIcon(TUid aAppUid, HBufC *&aFullFileName) const;

Description

Gets the full filename of a file containing application icons for the application with the specified UID.

An icon file can only be defined by applications providing an application registration file.

An icon file may be in any graphics format and contain one or more icons.

Parameters

TUid aAppUid The application specific UID. HBufC *&aFullFileName On return, the full filename of a file containing one or more application icons. Returns a pointer to the filename and transfers ownership to the caller.

Return value

TInt KErrNone, if successful; KErrNotFound, if a matching application could not be found, or an icon filename was not defined; KErrNotSupported, if the application does not provide an application registration file; otherwise one of the other system wide error codes.

IMPORT_C TInt GetAppViewIcon(TUid aAppUid, TUid aViewUid, HBufC *&aFullFileName) const;

Description

Gets the full filename of a file containing view-specific icons for the application with the specified UID and view.

A file containing view-specific icons can only be defined by applications providing an application registration file.

A view icon file may be in any graphics format and contain one or more view icons.

Parameters

TUid aAppUid The application specific UID. TUid aViewUid The UID identifying the view. HBufC *&aFullFileName On return, the full filename of a file containing one or more view icons. Returns a pointer to the filename and transfers ownership to the caller.

Return value

TInt KErrNone, if successful; KErrNotFound, if no matching application nor matching view could be found, or a view icon filename was not defined; KErrNotSupported, if the application does not provide an application registration file; otherwise one of the other system wide error codes.

Capability:

WriteDeviceData

Prevent addition of data type mappings by malicious programs.

IMPORT_C TInt InsertDataMapping(const TDataType &aDataType, TDataTypePriority aPriority, TUid aUid);

Description

Changes an existing data type mapping, or adds a new one.

If the data type is not currently mapped, a new mapping is added. If the data type is mapped, its mapping is replaced.

Parameters

const TDataType &aDataType A new or existing data type. TDataTypePriority aPriority The priority with which the application handles the data type. TUid aUid The UID of the application to associate with the data type.

Return value

TInt KErrNone on success, or a system-wide error code.

Capability:

WriteDeviceData

Prevent addition of data type mappings by malicious programs.

IMPORT_C TInt InsertDataMappingIfHigher(const TDataType &aDataType, TDataTypePriority aPriority, TUid aUid, TBool &aInserted);

Description

Changes an existing data type mapping, or adds a new one. If the data type is not currently mapped, it is added. If the data type is mapped with a priority lower than aPriority, the new mapping replaces the existing one. Otherwise, no change is made.

Parameters

const TDataType &aDataType A new or existing data type. TDataTypePriority aPriority The priority with which the application handles the data type. TUid aUid The UID of the application to associate with the data type. TBool &aInserted Non-zero if the new mapping was added or an existing mapping replaced, zero otherwise.

Return value

TInt KErrNone on success, or a system-wide error code.

Capability:

WriteDeviceData

Prevent removal of data type mappings by malicious programs.

IMPORT_C TInt DeleteDataMapping(const TDataType &aDataType);

Description

Removes an existing data type mapping.

Parameters

const TDataType &aDataType Data type whose mapping should be removed.

Return value

TInt KErrNone on success, or a system-wide error code.

Panic codes

USER 0 The specified data type cannot be found. Debug builds only.

IMPORT_C TInt ApplicationLanguage(TUid aAppUid, TLanguage &aLanguage) const;

Description

Determines the current language an application is using to display its user interface.

Parameters

TUid aAppUid The application specific UID. TLanguage &aLanguage On return, the application language.

Return value

TInt KErrNone, if successful; KErrNotFound, if a matching application could not be found; otherwise one of the other system wide error codes.

IMPORT_C void Close();

Description

Closes the session. Needs to be called to avoid memory leaks.

IMPORT_C void RegisterListPopulationCompleteObserver(TRequestStatus &aStatus) const;

Description

Registers an observer with apparc server to notify when the initial population of applist is completed

Parameters

TRequestStatus &aStatus Request status object. On successful completion contains KErrNone, otherwise one of the system-wide error codes.

See also:

• CancelListPopulationCompleteObserver()

IMPORT_C TInt CancelListPopulationCompleteObserver() const;

Description

Cancels the observer registered with apparc server to notify when the initial population of applist is completed

Return value

TInt KErrNone, if successful; otherwise one of the system-wide error codes.

IMPORT_C TInt MatchesSecurityPolicy(TBool &aMatches, TUid aAppUid, const TSecurityPolicy &aSecurityPolicy) const;

Description

Tests whether the given TSecurityPolicy matches with the application TSecurityPolicy.

Parameters

TBool &aMatches On return, contains the result. ETrue if the application TSecurityPolicy matches the given TSecurityPolicy or else EFalse TUid aAppUid Uid of the application for which the security policy has to be matched const TSecurityPolicy &aSecurityPolicy TSecurityPolicy to test whether the application with given uid matches with its TSecurityPolicy or not.

Return value

TInt KErrNone, if successful; otherwise one of the other system-wide error codes.

See also:

• TSecurityPolicy

IMPORT_C TInt RecognizeFilesL(const TDesC &aPath, CDataRecognitionResultArray &aResult) const;

Description

Gets the data (MIME) type for files in a specified directory. Because this call may take a long time to complete, the asynchronous version is strongly recommended. Furthermore, it is not possible to use this synchronous function while an asynchronous request is still active.

Parameters

const TDesC &aPath A valid path. Note that the path must end with a backslash. CDataRecognitionResultArray &aResult If the call was successful, this parameter contains the recognition result.

Return value

TInt KErrNone, if successful; otherwise one of the other system-wide error codes.

IMPORT_C void RecognizeFilesL(const TDesC &aPath, CDataRecognitionResultArray &aResult, TRequestStatus &aStatus);

Description

Gets the data (MIME) type for files in a specified directory.

Parameters

const TDesC &aPath A valid path. Note that the path must end with a backslash. CDataRecognitionResultArray &aResult If the call was successful, this parameter contains the recognition result. TRequestStatus &aStatus A request status object.

IMPORT_C TInt RecognizeFilesL(const TDesC &aPath, const TDesC8 &aDataType, CDataRecognitionResultArray &aResult) const;

Description

Gets the data (MIME) type for files in a specified directory. Because this call may take a long time to complete, the asynchronous version is strongly recommended. Furthermore, it is not possible to use this synchronous function while an asynchronous request is still active.

Parameters

const TDesC &aPath A valid path. Note that the path must end with a backslash. const TDesC8 &aDataType A data type filter. Wildcards are allowed. For example, "text*" would also add "text/plain" data types to the result. CDataRecognitionResultArray &aResult If the call was successful, this parameter contains the recognition result.

Return value

TInt KErrNone, if successful; otherwise one of the other system-wide error codes.

IMPORT_C void RecognizeFilesL(const TDesC &aPath, const TDesC8 &aDataType, CDataRecognitionResultArray &aResult, TRequestStatus &aStatus);

Description

Gets the data (MIME) type for files in a specified directory.

Parameters

const TDesC &aPath A valid path. Note that the path must end with a backslash. const TDesC8 &aDataType A data type filter. Wildcards are allowed. For example, "text*" would also add "text/plain" data types to the result. CDataRecognitionResultArray &aResult If the call was successful, this parameter contains the recognition result. TRequestStatus &aStatus A request status object

IMPORT_C void CancelRecognizeFiles();

Description

Cancels any outstanding asynchronous recognition requests.

IMPORT_C void NotifyOnDataMappingChange(TRequestStatus &aRequestStatus);

Description

Notification of changes in data-type mapping

This asynchronous function (whose corresponding "cancel" operation is CancelNotifyOnDataTypeMappingChange) completes when any data-type / application-UID association changes, i.e. when the default application handling a particular MIME-type changes.

Parameters

TRequestStatus &aRequestStatus As is normal for an asynchronous operation, this object is set to something other than KRequestPending when the asynchronous operation that has been triggered by this function completes.

IMPORT_C void CancelNotifyOnDataMappingChange();

Description

Cancellation of notification of changes in data-type mapping

This cancels the outstanding the NotifyOnDataTypeMappingChange issued by this client, if there is one outstanding. Otherwise it does nothing.

private: virtual IMPORT_C void RApaLsSession_Reserved1();

Description

private: virtual IMPORT_C void RApaLsSession_Reserved2();

Description

n/a

Description

ENoMoreAppsInList A possible return value from GetNextApp(), to indicate that there are no more applications in the list. EAppListInvalid Indicates that an RApaLsSession member function was called before the session's application list is fully populated.

TLaunchType

Description

Defines the way an application is launched.

ELaunchNewApp Launches a new instance of the application. ESwitchFiles Launches a new instance of the application if no existing instance of the application is running. If an instance of the application is already running, then it is brought to the foreground.