sl@0: // Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of the License "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // e32\drivers\resourceman\resourceman.cpp
sl@0: // 
sl@0: //
sl@0: 
sl@0: #include <drivers/resourcecontrol.h>
sl@0: #include <drivers/resourceman.h>
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Register a client with the resource manager
sl@0: 
sl@0: @param aClientId  A reference to a client ID: returns a unique handle if registration was
sl@0:                   successful, 0 otherwise.
sl@0: @param aName      Descriptor with name for client. The descriptor is created by the client
sl@0:                   in kernel heap or in kernel stack.
sl@0:                   NOTE: Name should ideally relate to component name and should take care
sl@0:                   of name uniqueness as this is not checked by resource manager unless 
sl@0: 				  DEBUG_VERSION macro is enabled.
sl@0: @param aType      Defines ownership
sl@0:                   EOwnerProcess - The client ID can be used by all thread in the process to
sl@0:                   call the resource manager API's
sl@0:                   EOwnerThread - The client ID can only be used by the thread that registered
sl@0:                   the client to resource manager to call the PRM API's
sl@0:                   By default this is set to EOwnerProcess.
sl@0: 
sl@0: @return           KErrNone     if the operation was successful,
sl@0:                   KErrNoMemory if a new client link was needed but could not be created and 
sl@0:                                added to the client list,
sl@0:                   KErrTooBig   if the length of the descriptor passed is greater than 32.
sl@0: 				  KErrAlreadyExists if the specified name already exists. This is valid only if 
sl@0: 				                    DEBUG_VERSION macro is enabled. 
sl@0: 				  KErrNotSupported if the number of expected kernel side clients is set to zero
sl@0: 									by PSL during initialisation.
sl@0:                   
sl@0: @pre Interrupts must be enabled.
sl@0: @pre Kernel must be unlocked.
sl@0: @pre No fast mutex can be held.
sl@0: @pre Call in a thread context, but not from null thread or DFC thread1.
sl@0: @pre Can be used in a device driver
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::RegisterClient(TUint& aClientId, const TDesC8& aName, TOwnerType aType)
sl@0: 	{
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::RegisterClient"));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("Client Name %S", &aName));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("OwnerType %d", aType));
sl@0:     return TInterface::RegisterClient(aClientId, aName, aType);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Deregister a client with the resource manager
sl@0: 
sl@0: @param aClientId    The ID of the client which is being deregistered
sl@0: 
sl@0: @return             KErrNone     if the operation was successful
sl@0:                     KErrNotFound if this client ID could not be found in the current
sl@0:                                  list of clients
sl@0: 		            KErrArgument if user side client ID is specified or client ID to be used
sl@0: 								 by Power Controller is specified.
sl@0: 		            KErrAccessDenied if client was registered to be thread relative and this API
sl@0: 						             is not called from the same thread. 
sl@0: 					
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::DeRegisterClient(TUint aClientId)
sl@0: 	{
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::DeRegisterClient"));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("Client ID %d", aClientId));
sl@0:     return TInterface::DeRegisterClient(aClientId);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Obtain the name of a registered client of the resource manager
sl@0: 
sl@0: @param aClientId       The ID of the client which is requesting the name of
sl@0:                        another client whose ID is specified in aTargetClientId.
sl@0: @param aTargetClientId The ID of the client whose name is being requested.
sl@0: @param aName           Descriptor to be filled with the name of the client.
sl@0: 				       The descriptor is created by the client in kernel stack or heap.
sl@0: 
sl@0: @return                KErrNone if the operation was successful
sl@0:                        KErrNotFound if this client ID (aTargetClientId) could not be
sl@0:                                     found in the current list of registered clients.
sl@0:                        KErrAccessDenied if the client ID (aClientId) could not be found
sl@0:                                         in the current list of registered clients or if the client was 
sl@0: 				                        registered to be thread relative and this API is not called from 
sl@0: 				                        the same thread.
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::GetClientName(TUint aClientId, TUint aTargetClientId, TDes8&
sl@0:  aName)
sl@0: 	{
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetClientName"));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aTargetClientId 0x%08x", aTargetClientId));
sl@0:     return TInterface::GetClientName(aClientId, aTargetClientId, aName);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Obtain the Id of registered client of the resource manager
sl@0: 
sl@0: @param aClientId       ID of the client which is requesting the ID of the another
sl@0:                        client whose name is specified in aClientName
sl@0: @param aClientName     Descriptor containing the name of the client whose ID is being
sl@0:                        requested. The client must create the descriptor in kernel stack
sl@0:                        or heap.
sl@0:                        NOTE: Resource manager does not check for uniqueness of client
sl@0:                        name during registration, so if there are multiple clients registered
sl@0:                        to PRM with same name it will return the ID of the first client encountered
sl@0: 				       with the specified name (order is not guaranteed).
sl@0: @param aTargetClientId Updates with ID of the requested client on success
sl@0: 
sl@0: @return                KErrNone if the operation was successful
sl@0:                        KErrNotFound if this client name could not be found in the current list 
sl@0: 					                of registered client.
sl@0:                        KErrAccessDenied if the client ID (aClientId) could not be found in the current
sl@0:                                        list of registered client or if the client was registered to 
sl@0: 									   be thread relative and this API is not called from the same thread.
sl@0:                        KErrTooBig if the length of the descriptor passed is greater than 32.
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::GetClientId(TUint aClientId, TDesC8& aClientName, TUint& aTargetClientId)
sl@0: 	{
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetClientId"));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientName %S", &aClientName));
sl@0:     return TInterface::GetClientId(aClientId, aClientName, aTargetClientId);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Obtain the ID of registered resource of the resource manager.
sl@0: NOTE: ID of the first matching name found in the resource list will be returned
sl@0: 
sl@0: @param aClientId      ID of the client which is requesting the ID of the
sl@0:                       resource, by specifying its name.
sl@0: @param aResourceName  Descriptor containing the name of the resource whose
sl@0:                       ID is being requested.The client must create descriptor in 
sl@0: 					  kernel stack or heap.
sl@0: @param aResourceId    Updates with ID of the requested resource on success
sl@0: 
sl@0: @return               KErrNone if the operation was successful
sl@0:                       KErrAccessDenied if the ID of the client could not be found in the
sl@0:                                        current list of registered clients or if the client was
sl@0: 						               registered to be thread relative and this API is not called
sl@0: 						               from the same thread. 
sl@0:                       KErrNotFound if this resource name could not be found in the current
sl@0:                                    list of registered resources.
sl@0: 		              KErrTooBig if the length of the descriptor passed is greater than 32. 
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::GetResourceId(TUint aClientId, TDesC8& aResourceName, TUint& aResourceId)
sl@0: 	{
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetResourceId"));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceName %S", &aResourceName));
sl@0:     return TInterface::GetResourceId(aClientId, aResourceName, aResourceId);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Request a structure containing information on a resource.
sl@0: 
sl@0: @param aClientId    ID of the client which is requesting the resource information
sl@0: @param aResourceId  ID of the resource whose information is being requested.
sl@0: @param aInfo        A pointer to descriptor containing resource information
sl@0:                     structure (TPowerResourceInfoV01) to be filled in
sl@0:                     with the requested resource information. The client must
sl@0:                     create the descriptor in kernel stack or heap.
sl@0: 
sl@0: @return             KErrNone if the operation was successful
sl@0:                     KErrAccessDenied if the client ID could not be found in the current list
sl@0:                                      of registered clients or if the client was registered to be
sl@0: 						             thread relative and this API is not called from the same thread.
sl@0:                     KErrNotFound if this resource ID could not be found in the current list
sl@0:                                  of controllable resource.
sl@0:                     KErrArgument if aInfo is NULL or size of descriptor passed is less than size of 
sl@0: 					             TPowerResourceInfoV01.
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::GetResourceInfo(TUint aClientId, TUint aResourceId, TAny* aInfo)
sl@0: 	{
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetResourceInfo"));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
sl@0:     return TInterface::GetResourceInfo(aClientId, aResourceId, aInfo);
sl@0: 	}
sl@0: 
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Request number of resources that the specified client (aTargetClientId) has
sl@0: requirement on resource level. Client ID starts from 1, so if 0 is specified in
sl@0: aTargetClientId, returns the total number of controllable resources registered with PRM.
sl@0: 
sl@0: @param aClientId       ID of the client that is requesting the number of resources for which
sl@0:                        the specified client (aTargetClientId) holds requirement on the
sl@0:                        resource level change.
sl@0: @param aTargetClientId ID of the client for which the number of resources that it 
sl@0: 					   has requested a level on is to be returned.
sl@0: @param aNumResource    Updated with the number of resources that the specified client
sl@0:                        has requirement on resource level change, if valid client
sl@0:                        ID is passed. If client ID is 0, updates the total number
sl@0:                        of resources registered with resource manager.
sl@0: 
sl@0: @return                KErrNone if the operation was successful.
sl@0:                        KErrAccessDenied if the client ID (aClientId) could not be found in the
sl@0:                                         current list of registered clients or if the client was registered
sl@0: 						                to be thread relative and this API is not called from the same thread.
sl@0:                        KErrNotFound if the client ID (aTargetClientId) could not be found in the
sl@0:                                     current list of registered clients and is not 0.
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::GetNumResourcesInUseByClient(TUint aClientId, TUint aTargetClientId, 
sl@0: 																 TUint& aNumResource)
sl@0: 	{
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetNumResourcesInUseByClient"));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aTargetClientId 0x%08x", aTargetClientId));
sl@0:     return TInterface::GetNumResourcesInUseByClient(aClientId, aTargetClientId, aNumResource);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Request information on resources.
sl@0: If client ID (aTargetClientId) is valid, aInfo is updated with the information 
sl@0: of the resources that this client requested a resource level.
sl@0: If client ID (aTargetClientId) is 0, aInfo is updated with the information of all the resources 
sl@0: registered with resource controller.
sl@0: The number of resources for which information will be provided will be equal or less than 
sl@0: the number specified in aNumResources.
sl@0: 
sl@0: @param aClientId       ID of the client which is requesting the resource information.
sl@0: @param aTargetClientId ID of the client. The information of all the resources on
sl@0:                        which it has requirement on resource level change is requested.
sl@0:                        Client ID starts from 1, so calling this API with client ID 0 will
sl@0:                        fill the details of all the controllable resource registered with
sl@0:                        resource manager starting from resource ID 1.
sl@0: @param aNumResources   Number of resource whose information needs to be filled in aInfo i.e,
sl@0:                        it specifies the size of aInfo array.
sl@0: @param aInfo           A pointer to an array of descriptor containing an information structure
sl@0:                        (TPowerResourceInfoV01) to be filled in with the information
sl@0:                        on the resources. It will be assumed that array allocated will be equal
sl@0:                        to the number passed in aNumResources. The client must create the array
sl@0:                        in Kernel stack or heap.
sl@0: 
sl@0: @return                KErrNone if the operation was successful
sl@0:                        KErrAccessDenied if client ID (aClientId) could not be found in the registered
sl@0:                                         client list or if the client was registered to be thread relative
sl@0: 										and this API is not called from the same thread.
sl@0:                        KErrNotFound if client ID (aTargetClientId) could not be found in the current list
sl@0:                                     of registered client and is also not 0.
sl@0:                        KErrArgument if aNumResources is 0 or aInfo is NULL or if size of aInfo is not 
sl@0: 					                sufficient to hold the resource information of number of resources 
sl@0: 									specified in aNumResource.
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::GetInfoOnResourcesInUseByClient(TUint aClientId, TUint aTargetClientId, 
sl@0: 																	TUint& aNumResource, TAny* aInfo)
sl@0: 	{
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetInfoOnResourcesInUseByClient"));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aTargetClientId 0x%08x", aTargetClientId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aNumResource 0x%08x", aNumResource));
sl@0:     return TInterface::GetInfoOnResourcesInUseByClient(aClientId, aTargetClientId, aNumResource, aInfo);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Request number of clients which has requirements on the resource level change of the specified
sl@0: resource. Resource ID starts from 1, so 0 can be used to get the number of clients
sl@0: registered with resource manager.
sl@0: 
sl@0: @param aClientId         ID of the client which is requesting number of clients
sl@0:                          holding requirement on specified resource.
sl@0: @param aResourceId       ID of the resource.
sl@0: @param aNumClient        Upon success, updated with number of clients having a requirement
sl@0:                          on resource level for the specified resource, if valid resource ID is specified.
sl@0:                          If resource ID is 0, then it is updated with number of clients
sl@0:                          registered with PRM.
sl@0: 
sl@0: @return                  KErrNone if the operation was successful
sl@0:                          KErrAccessDenied if the client ID could not found in the current list of
sl@0:                                           registered clients or if the client was registered to be thread 
sl@0: 						                  relative and this API is not called from the same thread.
sl@0:                          KErrNotFound If this resource ID could not be found in the current list
sl@0:                                       of registered resource and is also not 0.
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::GetNumClientsUsingResource(TUint aClientId, TUint aResourceId, TUint& aNumClients)
sl@0: 	{
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetNumClientsUsingResource"));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
sl@0:     return TInterface::GetNumClientsUsingResource(aClientId, aResourceId, aNumClients);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Request information on clients
sl@0: If resource ID is valid, aInfo is updated with the information of the clients
sl@0: which have a requirements on the resource level for the specified resource
sl@0: If resource ID is 0, aInfo is updated with the information of the clients registered
sl@0: with resource manager, starting from client ID 1.
sl@0: The number of clients for which information will be provided will be equal to or less
sl@0: than the number specified in a NumClients.
sl@0: 
sl@0: @param aClientId        ID of the client which is requesting the information 
sl@0: @param aResourceId      Id of the resource.
sl@0: @param aNumClients		Number of clients whose information needs to be filled in aInfo
sl@0: 						ie, it specifies the size of aInfo array.
sl@0: @param aInfo            A pointer to an array of descriptor containing an information
sl@0:                         structure (TPowerClientInfoV01) to be filled in with
sl@0:                         the information on the client. It will be assumed that array
sl@0:                         allocated will be equal to the number passed in aNumClients.
sl@0:                         The Client must create the array of descriptors in kernel stack
sl@0:                         or heap.
sl@0: 
sl@0: @return                 KErrNone if the operation was successful.
sl@0:                         KErrNotFound if resource ID could not be found in the registered resource list and is 
sl@0: 						             also not 0.
sl@0: 		                KErrAccessDenied if client ID (aClientId) could not be found in the registered client list
sl@0: 						                 or if the client was registered to be thread relative and this API is not 
sl@0: 						                 called from the same thread. 
sl@0:                         KErrArgument if aNumClients is 0 or aInfo is NULL or if size of aInfo is not sufficient 
sl@0: 						             to hold client information of specified client number in aNumClients.
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::GetInfoOnClientsUsingResource(TUint aClientId, TUint aResourceId, 
sl@0: 																  TUint& aNumClients, TAny* aInfo)
sl@0: 	{
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetInfoOnClientsUsingResource"));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aNumClients 0x%08x", aNumClients));
sl@0:     return TInterface::GetInfoOnClientsUsingResource(aClientId, aResourceId, aNumClients, aInfo);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Request changing the state of a resource
sl@0: NOTE: If a resource callback is specified for instantaneous resource, then callback
sl@0:       will be called after resource change and will be executed in the context of the
sl@0:       client thread.
sl@0:       If a resource callback is specified for long latency reosurces, then it will be
sl@0:       executed asynchronously.
sl@0:       When the request is accepted the API returns immediately and the calling thread
sl@0:       is unblocked: the callback (called in the client's context) will be invoked when
sl@0:       the resource change finally takes place.
sl@0:       If aCb is not specified (NULL by default) the API executes synchronously and will
sl@0:       only return when the resource change has taken place for long latency resource.
sl@0:       The client thread is blocked throughout
sl@0:       When state change for a shared resource is requested, only minimum state that
sl@0:       satisfy the requirement is guaranteed and it is not guaranteed for the absolute
sl@0:       value change.
sl@0: 
sl@0: @param aClientId   ID of the client which is requesting the resource change.
sl@0: @param aResourceId ID of the resource whose state is to be changed.
sl@0: @param aNewState   The new state of the resource. This could be a binary value for a
sl@0:                    binary resource, an integer level for a multilevel resource or some
sl@0:                    platform specific token for a multi-property resource.
sl@0: @param aCb         For Long latency resource
sl@0:                        A pointer to a resource callback object which encapsulates a
sl@0:                        callback function to be called whenever the resource state change
sl@0:                        happens (if left NULL the API will execute synchrounously).
sl@0:                    For Instantaneous resource
sl@0:                        A pointer to a resource callback object which encapsulates a callback
sl@0:                        function to be called after resource change. This executes in the
sl@0:                        context of the client thread.
sl@0: 
sl@0: @return            KErrNone If the API is to be executed synchronously it indicates the change was
sl@0:                             successful, if the API is to be executed asynchronously it indicates
sl@0:                             the request to change the resource state has been accepted.
sl@0:                    KErrNotFound if the resource ID could not be found in the current list of
sl@0:                                 controllable resources.
sl@0:                    KErrAccessDenied if the client ID could not be found in the list of
sl@0:                                     registered clients or if the client was registered to be thread 
sl@0: 						            relative and this API is not called from the same thread.
sl@0:                    KErrNotReady if the request is issued before the resource controller completes its
sl@0:                                 internal initialisation.
sl@0:                    KErrUnderflow if the client has exceeded the reserved number of
sl@0:                                  SPowerResourceClientLevel and the free pool is empty or if it is
sl@0:                                  an asynchronous operation on long latency resource and the client has exceeded 
sl@0: 					             the reserved number of TPowerRequest and the free pool is empty.
sl@0: 				   KErrArgument if requested level is out of range (outside of min and max levels)
sl@0: 				   KErrPermissionDenied if the requested state of the resource is not accepted by its dependents.
sl@0: 				                        This error is valid only for dependent resource state change in extened
sl@0: 										version of PRM.
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver
sl@0: @pre Do not call synchronous version from DFC thread 0 for long latency resource
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::ChangeResourceState(TUint aClientId , TUint aResourceId, 
sl@0: 														TInt aNewState, TPowerResourceCb* aCb)
sl@0: 	{
sl@0: 	__KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::ChangeResourceState"));
sl@0: 	__KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0: 	__KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
sl@0: 	__KTRACE_OPT(KRESMANAGER, Kern::Printf("aNewState 0x%08x", aNewState));
sl@0: 	return TInterface::ChangeResourceState(aClientId, aResourceId, aNewState, aCb);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Request the state of the resource synchronously. Client thread will be blocked throughout.
sl@0: 
sl@0: @param aClientId     ID of the client which is requesting the resource state.
sl@0: @param aResourceId   ID of the resource whose state is being requested.
sl@0: @param aCached       If ETrue, cached value will be updated in aState.
sl@0:                      If EFalse, aState will be updated after the resource
sl@0:                      state is read from resource.
sl@0: @param aState        Returns the resource state if operation was successful. This
sl@0:                      could be a binary value for a binary resource, an integer level
sl@0:                      for a multilevel resource or some platform specific tolen for a
sl@0:                      multi-property resource.
sl@0: @param aLevelOwnerId Returns the Id of the client that is currently the owner of the resource.
sl@0: 					 -1	is returned when no client is owner of the resource.
sl@0: 
sl@0: @return              KErrNone if operation was successful
sl@0:                      KErrAccessDenied if the client ID could not be found in the current list
sl@0:                                       of registered clients or if the client was registered to be thread
sl@0: 						              relative and this API is not called from the same thread.
sl@0:                      KErrNotFound if this resource ID could not be found in the current list
sl@0:                                   of controllable resources.
sl@0:                      KErrNotReady if the request is issued before the resource controller completes
sl@0:                                   its internal initialization.
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver
sl@0: @pre Do not call from DFC thread 0 for long latency resource with caching disabled.
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::GetResourceState(TUint aClientId, TUint aResourceId, TBool aCached, 
sl@0: 													 TInt& aState, TInt& aLevelOwnerId)
sl@0: 	{
sl@0: 	__KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetResourceState"));
sl@0: 	__KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0: 	__KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
sl@0: 	__KTRACE_OPT(KRESMANAGER, Kern::Printf("aCached 0x%08x", aCached));
sl@0: 	return TInterface::GetResourceState(aClientId, aResourceId, aCached, aState, aLevelOwnerId);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Request the state of the resource asynchrounously.
sl@0: 
sl@0: @param aClientId   ID of the client which is requesting the resource state.
sl@0: @param aResourceId ID of the resource whose state is being requested.
sl@0: @param aCached     If ETrue, cached value will be updated in aState
sl@0:                    If EFalse, will be updated after the resource state is read from resource
sl@0: @param aCb         For long latency resource:
sl@0:                       A pointer to a resource callback object which encapsulates a callback function
sl@0:                       to be called whenever the state of the resource is available for the long
sl@0:                       latency resource (executes in the context of resource manager)
sl@0:                    For instantaneous resource:
sl@0:                       A pointer to a resource callback object which encapsulates a callback
sl@0:                       function to be called after the resource state is read. This is executed
sl@0:                       synchronously in the context of the calling thread.
sl@0:                       NOTE: The client must create the callback object in kernel heap or
sl@0:                             data section.
sl@0: 
sl@0: @return            KErrNone if the operation was successful
sl@0:                    KErrAccessDenied if the client ID could not be found in the current list
sl@0:                                     of registered clients or if the client was registered to be
sl@0: 						            thread relative and this API is not called from the same thread.
sl@0:                    KErrNotFound if this resource ID could not be found in the current list
sl@0:                                 of controllable resources.
sl@0:                    KErrNotReady if the request is issued before the resource controller completes
sl@0:                                 its internal initialisation
sl@0:                    KErrUnderflow if the client has exceeded the reserved number of TPowerRequest
sl@0:                                  and the TPowerRequest free pool is empty for long latency resource.
sl@0: 		           KErrArgument if callback object is NULL.
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::GetResourceState(TUint aClientId, TUint aResourceId, TBool aCached, TPowerResourceCb& aCb)
sl@0: 	{
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::GetResourceState"));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aCached 0x%08x", aCached));
sl@0:     return TInterface::GetResourceState(aClientId, aResourceId, aCached, aCb);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5  
sl@0: 
sl@0: Cancel an asynchronous request(or its callback).
sl@0: 
sl@0: @param aClientId       ID of the client which is requesting the cancellation of the request.
sl@0: @param aResourceId     ID for the resource which the request that is being cancelled operates
sl@0:                        upon.
sl@0: @param aCb             A reference to the resource callback object specified with the request
sl@0:                        that is being cancelled.
sl@0: 
sl@0: @return                KErrCancel if the request was cancelled.
sl@0:                        KErrNotFound if this resource ID could not be found in the current list of 
sl@0: 					                controllable resources.
sl@0:                        KErrCompletion if request is no longer pending.
sl@0:                        KErrAccessDenied if the client ID could not be found in the current list of registered
sl@0: 		                                clients or if the client was registered to be thread relative and this API
sl@0: 						                is not called from the same thread or if client is not the same that 
sl@0: 						                requested the resource state change.
sl@0: 		               KErrInUse if the request cannot be cancelled as processing of the request already started 
sl@0: 				                 and will run to completion. 
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::CancelAsyncRequestCallBack(TUint aClientId, TUint aResourceId, TPowerResourceCb& aCb)
sl@0: 	{
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::CancelAsyncRequestCallback"));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
sl@0:     return TInterface::CancelAsyncRequestCallBack(aClientId, aResourceId, aCb);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Request notification of changes to the state of a resource.
sl@0: 
sl@0: NOTE: This API should return immediately; however the notification will
sl@0: only happen when a resource change occurs.Notification request is idempotent, 
sl@0: if the same notification has already been requested for this resource ID, 
sl@0: the API returns with no further action. Notifications remain queued until 
sl@0: they are cancelled.
sl@0: 
sl@0: @param aClientId     ID of the client which is requesting the notification.
sl@0: @param aResourceId   ID of the resource for which notification of state changes
sl@0:                      is being requested.
sl@0: @param aN            A reference to a notification object which encapsulates a callback
sl@0:                      function to be called whenever a resource state change takes place.
sl@0:                      NOTE: The client must create the notification object in kernel heap
sl@0:                            or data section.
sl@0: 
sl@0: @return              KErrNone if the operation of requesting a notification was successful.
sl@0:                      KErrNotFound if this resource ID could not be found in the current list
sl@0:                                   of controllable resources.
sl@0:                      KErrAccessDenied if the client ID could not be found in the current
sl@0:                                       list of registered clients or if the client was registered to be thread
sl@0: 						              relative and this API is not called from the same thread.
sl@0: 		             KErrInUse if the passed notification object is used already.
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::RequestNotification(TUint aClientId, TUint aResourceId, DPowerResourceNotification& aN)
sl@0: 	{
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::RequestNotification"));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
sl@0:     return TInterface::RequestNotification(aClientId, aResourceId, aN);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Request notification when the state of a resource reaches a specified threshold or
sl@0: goes above or below that threshold (for multilevel resource only) based on direction.
sl@0: In other words it is issued when a threshold on the specified resource state is crossed
sl@0: in the direction specified.
sl@0: 
sl@0: NOTE:This API should return immediately; however the notification will only
sl@0: happen when a resource change occurs. Notification request is idempotent, 
sl@0: if the same notification has already been requested for this resource ID, 
sl@0: the API returns with no further action. Notification remain queued until 
sl@0: they are cancelled.
sl@0: 
sl@0: @param aClientId    ID of the client which is requesting the notification.
sl@0: @param aResourceId  ID for the resource whose notification of state changes is
sl@0:                     being requested.
sl@0: @param aN           A reference to a notification object which encapsulates a callback
sl@0:                     function to be called whenever the conditions to issue the notification
sl@0:                     (specified in the API) are met.
sl@0:                     NOTE: The client must create the notification object in kernel heap
sl@0:                           or data section.
sl@0: @param aThreshold   The level of the resource state that will trigger the notification
sl@0:                     when reached.
sl@0: @param aDirection   Specifies the direction of change of the resource state that will
sl@0:                     trigger a notification. EFalse means the notification will be issued
sl@0:                     when the resource state change to a specified threshold value or below
sl@0:                     the specified threshold, ETrue means the notification will be issued
sl@0:                     when the resource state change to a specified threshold value or above
sl@0:                     the specified threshold.
sl@0: 
sl@0: @return             KErrNone if the operation of requesting a notification was successful.
sl@0:                     KErrNotFound if this resource ID could not be found in the current list
sl@0:                                  of controllable reosurces.
sl@0:                     KErrAccessDenied if the client ID could not be found in the list of
sl@0:                                      registered clients or if the client was registered to be
sl@0: 						             thread relative and this API is not called from the same thread.
sl@0: 		            KErrInUse if the passed notification object is used already.
sl@0: 		            KErrArgument if the specified threshold is out of range.
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::RequestNotification(TUint aClientId, TUint aResourceId, DPowerResourceNotification& aN,
sl@0: 														TInt aThreshold, TBool aDirection)
sl@0: 	{
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::RequestNotification"));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aThreshold 0x%08x", aThreshold));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aDirection 0x%08x", aDirection));
sl@0:     return TInterface::RequestNotification(aClientId, aResourceId, aN, aThreshold, aDirection);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Cancel and remove from queue a previously issued request for notification on a
sl@0: resource state change.
sl@0: 
sl@0: @param aClientId    ID of the client which is requesting to cancel the notification
sl@0: @param aResourceId  ID of the resource whose pending notification of state changes
sl@0:                     is being cancelled.
sl@0: @param aN           A reference to the notification object that was associated with
sl@0:                     the notification request that is being cancelled. This will be
sl@0:                     used to identify the notification that is being cancelled.
sl@0: 
sl@0: @return             KErrCancel if the notification request was successfully cancelled.
sl@0:                     KErrNotFound if the specified notification object is not found in the current list
sl@0: 					             of notification objects for the specified resource.
sl@0:                     KErrAccessDenied if the client requesting the cancellation is not the same
sl@0:                                      which registered the notification or if the resource id does not
sl@0: 						             match or if the client ID could not be found in the list of 
sl@0:              						 registered clients or if the client was registered to be 
sl@0: 			             			 thread relative and this API is not called from the same thread.
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::CancelNotification(TUint aClientId, TUint aResourceId, DPowerResourceNotification& aN)
sl@0: 	{
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::CancelNotification"));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
sl@0:     return TInterface::CancelNotification(aClientId, aResourceId, aN);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Request pre-allocation of specified number of client level and request message objects.
sl@0: 
sl@0: @param aClientId  ID of the client which is requesting the pre-allocation.
sl@0: @param aNumCl     Number of client level objects that needs to be pre-allocated
sl@0:                   for this client.
sl@0: @param aNumRm     Number of request message objects that needs to be pre-allocated
sl@0:                   for this client.
sl@0: 
sl@0: @return           KErrNone if the allocation was successful
sl@0:                   KErrAccessDenied if the client ID could not be found in the list of
sl@0:                                    registered clients or if the client was registered to be 
sl@0: 						           thread relative and this API is not called from the same thread.
sl@0:                   KErrNoMemory if there is no sufficient memory for allocation of requested
sl@0:                                number of objects.
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::AllocReserve(TUint aClientId, TUint8 aNumCl, TUint8 aNumRm)
sl@0: 	{
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::AllocReserve"));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aNumCl 0x%02x", aNumCl));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aNumRm 0x%02x", aNumRm));
sl@0:     return TInterface::AllocReserve(aClientId, aNumCl, aNumRm);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Request to deregister client level from the specified resource for the specified client.
sl@0: 
sl@0: @param aClientId	ID of the client which is requesting the deregistration of client level.
sl@0: @param aResourceId	ID of the resource from which to remove the specified clients 'client level'.
sl@0: 
sl@0: @return             KErrNone if successful
sl@0: 		            KErrAccessDenied if the client ID could not be found in the list of registered clients or
sl@0: 							         if the client was registered to be thread relative and this API is not 
sl@0: 							         called from the same thread.
sl@0: 		            KErrNotFound if the resource ID could not be found in the current list of controllable 
sl@0: 							     resources or if the client is not holding any level with the specified 
sl@0: 							     resource (no client level found for the specified client).
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver.
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::DeRegisterClientLevelFromResource(TUint aClientId, TUint aResourceId)
sl@0: 	{
sl@0: 	__KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::DeRegisterClientLevelFromResource"));
sl@0: 	__KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0: 	__KTRACE_OPT(KRESMANAGER, Kern::Printf("aResourceId 0x%08x", aResourceId));
sl@0: 	return TInterface::DeRegisterClientLevelFromResource(aClientId, aResourceId);
sl@0: 	}
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.5
sl@0: 
sl@0: Interface to provide extended functionality.This provides support
sl@0: to register and deregister dynamic resources and handling of resource dependency, registering
sl@0: and deregistering resource dependency.
sl@0: This is not supported in basic version
sl@0: It is used for getting version (supported in both version). 
sl@0: 
sl@0: @pre Interrupts must be enabled
sl@0: @pre Kernel must be unlocked
sl@0: @pre No fast mutex can be held
sl@0: @pre Call in a thread context but not from null thread or DFC thread1
sl@0: @pre Can be used in a device driver.
sl@0: */
sl@0: EXPORT_C TInt PowerResourceManager::ControlIO(TUint aClientId, TUint aFunction, TAny* aParam1, TAny* aParam2, 
sl@0: 											  TAny* aParam3)
sl@0:     {
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf(">PowerResourceManager::ControlIO"));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aClientId 0x%08x", aClientId));
sl@0:     __KTRACE_OPT(KRESMANAGER, Kern::Printf("aFunction %d", aFunction));
sl@0:     return TInterface::ControlIO(aClientId, aFunction, aParam1, aParam2, aParam3);
sl@0: 	}
sl@0: 
sl@0: