Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
// Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// under the terms of "Eclipse Public License v1.0"
// which accompanies this distribution, and is available
// at the URL "http://www.eclipse.org/legal/epl-v10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
//
// Contributors:
//
// Description:
// The API definitions required for the use of the ECOM framework by a client
// are contained / defined here.
//
//
/**
@file
@publishedAll
@released
*/
#ifndef __ECOM_H__
#define __ECOM_H__
// ____________________________________________________________________________
// INCLUDES
#include <e32base.h>
#include <s32std.h>
#include <f32file.h>
#include <ecom/ecomerrorcodes.h>
#include <ecom/ecomresolverparams.h>
#include <ecom/implementationinformation.h>
// ____________________________________________________________________________
// CONSTANTS
class CGlobalData;
/**
The UID identifying the ROM-Only CResolver Interface Implementation.
This resolver only returns implementations present on R/O internal media
(built-in) or upgrades of such implementations on R/W media. It does not
return implementations that solely reside on R/W media.
*/
const TUid KRomOnlyResolverUid = {0x10009D92};
// ____________________________________________________________________________
// CLASSES
/**
The REComSession singleton class provides an API to identify (resolution),
instantiate, and destroy interface class implementations requested by
ECOM clients. It manages the session connection to the ECOM Server itself so
that typically only one connection is made to the ECOM Server per thread.
It provides an un-initialise function where it releases memory and handles
of unused plug-ins, see the FinalClose() function. It also ensures that all
necessary clean-up is performed in the event of a Leave by any of the
ListImplementationsL() or CreateImplementationL() methods.
Note: Although a public default constructor is provided in this class
it is strongly recommended this object is never created by users of this
API on the stack or heap by value. To access the non-static methods of this
API use the static OpenL() method to obtain a pointer or a
reference to the single reference counted session in use. Close() must be
called when finished with.
Special care must be taken when using aInstanceKey. It is a 32-bit instance key
that is returned from a call to one of the CreateImplementationL() methods.
This instance key must only be used with DestroyedImplementation() to identify
the implementation instance for destruction, or GetImplementationUidL() to
retrieve the Implementation Uid of the instance it refers to.
No meaning must be attached to this instance key by ECOM clients
and it must not be used for any other purpose.
@see REComSession::FinalClose()
*/
class REComSession : public RSessionBase
{
friend class CGlobalData;
public: // publishedAll APIs
// Available for use by all clients
IMPORT_C REComSession();
IMPORT_C static REComSession& OpenL();
IMPORT_C void Close();
// Get Implementation Uid from an Instance Key
IMPORT_C static TUid GetImplementationUidL(
TUid aInstanceKey);
// Destroy Implementation API declaration
IMPORT_C static void DestroyedImplementation(
TUid aInstanceKey);
// See developer documentation for use of FinalClose.
IMPORT_C static void FinalClose();
// Notification API declarations
//
IMPORT_C void NotifyOnChange(TRequestStatus& aStatus);
IMPORT_C void CancelNotifyOnChange(TRequestStatus& aStatus);
// List implementations API declarations
//
// Use LI1 to list all implementations, unfiltered.
// Use LI2 when default resolving required on the returned list.
// Use LI3 when custom resolving required on the returned list.
// ListImplementationsL - LI1
IMPORT_C static void ListImplementationsL(
TUid aInterfaceUid,
RImplInfoPtrArray& aImplInfoArray);
// ListImplementationsL - LI2
IMPORT_C static void ListImplementationsL(
TUid aInterfaceUid,
const TEComResolverParams& aResolutionParameters,
RImplInfoPtrArray& aImplInfoArray);
// ListImplementationsL - LI3
IMPORT_C static void ListImplementationsL(
TUid aInterfaceUid,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid,
RImplInfoPtrArray& aImplInfoArray);
// Use LI7 to list all implementations, unfiltered and with no capability chaeck.
// Use LI8 when default resolving required on the returned list and with no capability chaeck.
// Use LI9 when custom resolving required on the returned list and with no capability chaeck.
// ListImplementationsL - LI7
IMPORT_C static void ListImplementationsL(
TUid aInterfaceUid,
RImplInfoPtrArray& aImplInfoArray,TBool aCapabilityCheck);
// ListImplementationsL - LI8
IMPORT_C static void ListImplementationsL(
TUid aInterfaceUid,
const TEComResolverParams& aResolutionParameters,
RImplInfoPtrArray& aImplInfoArray,TBool aCapabilityCheck);
// ListImplementationsL - LI9
IMPORT_C static void ListImplementationsL(
TUid aInterfaceUid,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid,
RImplInfoPtrArray& aImplInfoArray,TBool aCapabilityCheck);
// Create implementations API declarations
//
// When Implementation UID is known:
// Use CI1, CI2.
// Use CI3, CI4 when you have construction parameters.
//
// When the Interface UID is known and default resolving is required:
// Use CI5, CI6.
// Use CI7, CI8 when you have construction parameters.
//
// When the Interface UID is known and custom resolving is required:
// Use CI9, CI10.
// Use CI11, CI12 when you have construction parameters.
// CreateImplementationL - CI1
IMPORT_C static TAny* CreateImplementationL(
TUid aImplementationUid,
TUid& aInstanceKey);
// CreateImplementationL - CI2
IMPORT_C static TAny* CreateImplementationL(
TUid aImplementationUid,
TInt32 aKeyOffset);
// CreateImplementationL - CI3
IMPORT_C static TAny* CreateImplementationL(
TUid aImplementationUid,
TUid& aInstanceKey,
TAny* aConstructionParameters);
// CreateImplementationL - CI4
IMPORT_C static TAny* CreateImplementationL(
TUid aImplementationUid,
TInt32 aKeyOffset,
TAny* aConstructionParameters);
// CreateImplementationL - CI5
IMPORT_C static TAny* CreateImplementationL(
TUid aInterfaceUid,
TUid& aInstanceKey,
const TEComResolverParams& aResolutionParameters);
// CreateImplementationL - CI6
IMPORT_C static TAny* CreateImplementationL(
TUid aInterfaceUid,
TInt32 aKeyOffset,
const TEComResolverParams& aResolutionParameters);
// CreateImplementationL - CI7
IMPORT_C static TAny* CreateImplementationL(
TUid aInterfaceUid,
TUid& aInstanceKey,
TAny* aConstructionParameters,
const TEComResolverParams& aResolutionParameters);
// CreateImplementationL - CI8
IMPORT_C static TAny* CreateImplementationL(
TUid aInterfaceUid,
TInt32 aKeyOffset,
TAny* aConstructionParameters,
const TEComResolverParams& aResolutionParameters);
// CreateImplementationL - CI9
IMPORT_C static TAny* CreateImplementationL(
TUid aInterfaceUid,
TUid& aInstanceKey,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid);
// CreateImplementationL - CI10
IMPORT_C static TAny* CreateImplementationL(
TUid aInterfaceUid,
TInt32 aKeyOffset,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid);
// CreateImplementationL - CI11
IMPORT_C static TAny* CreateImplementationL(
TUid aInterfaceUid,
TUid& aInstanceKey,
TAny* aConstructionParameters,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid);
// CreateImplementationL - CI12
IMPORT_C static TAny* CreateImplementationL(
TUid aInterfaceUid,
TInt32 aKeyOffset,
TAny* aConstructionParameters,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid);
public: // publishedPartner APIs
// Extended interfaces API declarations available for use by
// all system software i.e by phone manufacturers and internally (i.e. not supported for use by 3rd parties)
// See Symbian OS Developer Library and ECOM How To/FAQ documentation.
// List implementations API declarations
//
// Use L14 to list all implementations which satisfy interface, extended
// interfaces
// Use L15 to list all implementations which satisfy interface, extended
// interfaces when default resolving required on the list returned
// Use L16 to list all implementations which satisfy interface, extended
// interfaces when custom resolving required on the list returned
// ListImplementationsL - LI4
IMPORT_C static void ListImplementationsL(
TUid aInterfaceUid,
RExtendedInterfacesArray& aExtendedInterfaces,
RImplInfoPtrArray& aImplInfoArray);
// ListImplementationsL - LI5
IMPORT_C static void ListImplementationsL(
TUid aInterfaceUid,
RExtendedInterfacesArray& aExtendedInterfaces,
const TEComResolverParams& aResolutionParameters,
RImplInfoPtrArray& aImplInfoArray);
// ListImplementationsL - LI6
IMPORT_C static void ListImplementationsL(
TUid aInterfaceUid,
RExtendedInterfacesArray& aExtendedInterfaces,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid,
RImplInfoPtrArray& aImplInfoArray);
// Create implementations API declarations
//
// When the interface UID and the extended interface UID's are known
// and default resolving is required. The construction parameters may
// optionally be provided.
// Use CI13: Instance key is returned
// Use CI14: An offset to aInstanceKey returned by the ECom framework
// to identify this instance to the framework
// When the interface UID and the extended interface UID's are known
// and custom resolving is required. The construction parameters may
// optionally be provided.
// Use CI15: Instance key is returned
// Use CI16: An offset to aInstanceKey returned by the ECom framework
// to identify this instance to the framework
// CreateImplementationL - CI13
IMPORT_C static TAny* CreateImplementationL(
TUid aInterfaceUid,
const RExtendedInterfacesArray& aExtendedInterfaces,
TUid& aInstanceKey,
const TEComResolverParams& aResolutionParameters,
TAny* aConstructionParameters = NULL);
// CreateImplementationL - CI14
IMPORT_C static TAny* CreateImplementationL(
TUid aInterfaceUid,
const RExtendedInterfacesArray& aExtendedInterfaces,
TInt32 aKeyOffset,
const TEComResolverParams& aResolutionParameters,
TAny* aConstructionParameters = NULL);
// CreateImplementationL - CI15
IMPORT_C static TAny* CreateImplementationL(
TUid aInterfaceUid,
const RExtendedInterfacesArray& aExtendedInterfaces,
TUid& aInstanceKey,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid,
TAny* aConstructionParameters = NULL);
// CreateImplementationL - CI16
IMPORT_C static TAny* CreateImplementationL(
TUid aInterfaceUid,
const RExtendedInterfacesArray& aExtendedInterfaces,
TInt32 aKeyOffset,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid,
TAny* aConstructionParameters = NULL);
// Extended Interface query and management API declarations
//
IMPORT_C static TAny* GetExtendedInterfaceL(
const TUid& aInstanceKey,
const TUid& aExtendedInterfaceUid);
IMPORT_C static void ListExtendedInterfacesL(
const TUid& aImplementationUid,
RExtendedInterfacesArray& aIfInfo);
IMPORT_C static void ManuallyReleaseExtendedInterfaceL(
const TUid& aInstanceKey,
const TUid& aExtendedInterfaceUid);
private: // @internalComponent APIs
// This API is for internal testing purposes.Should not be used externally by clients.
static REComSession& OpenLC();
void ConstructL();
void ReallyClose();
void ListImplementationsL(
TInt aServiceId,
TUid aInterfaceUid,
const RExtendedInterfacesArray& aExtendedInterfaces,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid,
RImplInfoPtrArray& aImplInfoArray,
TBool aCapabilityCheck = ETrue);
TAny* ResolveAndCreateImplL(
TUid aImplementationUid,
TUid& aInstanceKey,
TAny* aCreationParameters,
TBool aCreationParamsFlag);
TAny* ResolveAndCreateImplL(
TUid aInterfaceUid,
const TEComResolverParams& aResolutionParameters,
TUid& aInstanceKey,
TAny* aCreationParameters,
TBool aCreationParamsFlag);
TAny* ResolveAndCreateImplL(
TUid aInterfaceUid,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid,
TUid& aInstanceKey,
TAny* aCreationParameters,
TBool aCreationParamsFlag);
TAny* ResolveAndCreateImplL(
TUid aInterfaceUid,
const RExtendedInterfacesArray& aExtendedInterfaces,
const TEComResolverParams& aResolutionParameters,
TUid& aInstanceKey,
TAny* aCreationParameters,
TBool aCreationParamsFlag);
TAny* ResolveAndCreateImplL(
TUid aInterfaceUid,
const RExtendedInterfacesArray& aExtendedInterfaces,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid,
TUid& aInstanceKey,
TAny* aCreationParameters,
TBool aCreationParamsFlag);
TAny* ResolveAndCreateImplL(
TInt aServiceId,
TUid aInterfaceUid,
const RExtendedInterfacesArray& aExtendedInterfaces,
const TEComResolverParams& aResolutionParameters,
TUid aResolverUid,
TUid& aInstanceKey,
TAny* aCreationParameters,
TBool aCreationParamsFlag);
void ProcessListExtendedInterfacesL(
const TUid& aImplementationUid,
RExtendedInterfacesArray& aIfInfo);
void PackMatchStrAndExtendedInterfacesL(
const TEComResolverParams& aResolutionParameters,
const RExtendedInterfacesArray& aExtendedInterfaces,
RBuf8& aMatchStrExtInfBuf);
public: // @internalComponent APIs
// Internal methods used inside ECOM, not for client use.
// This API is for internal testing purposes.
IMPORT_C static void SetGetParametersL(const TIpcArgs &aArgs);
private:
/** Not used */
TInt iReserved1;
/** not used */
TInt iReserved3;
/** not used */
TInt iReserved2;
};
#endif // __ECOM_H__