williamr@2: /*
williamr@2: * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:
williamr@2: * Name        : pls.h
williamr@2: * Part of     : Client API for ewsd library
williamr@2: * Contains the client API for using the emulator WSD library
williamr@2: * Redistribution and use in source and binary forms, with or without 
williamr@2: * modification, are permitted provided that the following conditions are met:
williamr@2: * Redistributions of source code must retain the above copyright notice, this 
williamr@2: * list of conditions and the following disclaimer. 
williamr@2: * Redistributions in binary form must reproduce the above copyright notice, 
williamr@2: * this list of conditions and the following disclaimer in the documentation 
williamr@2: * and/or other materials provided with the distribution. 
williamr@2: * Neither the name of the <ORGANIZATION> nor the names of its contributors 
williamr@2: * may be used to endorse or promote products derived from this software 
williamr@2: * without specific prior written permission. 
williamr@2: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
williamr@2: * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
williamr@2: * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
williamr@2: * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
williamr@2: * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
williamr@2: * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
williamr@2: * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
williamr@2: * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
williamr@2: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
williamr@2: * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2:  
williamr@2: #ifndef __PLS_H__
williamr@2: #define __PLS_H__
williamr@2: 
williamr@2: #ifdef __WINSCW__
williamr@2:  
williamr@2: #include <ewsd.h>
williamr@2: 
williamr@2: // Panic strings
williamr@2: _LIT(KVirtualAllocFailure, "WSD VirtualAlloc() failed");
williamr@2: _LIT(KPLSInitFailed, "WSD PLS init failed");
williamr@2: _LIT(KWsdArrayFull, "WSD process or lib array full");	
williamr@2: 
williamr@2: /**  
williamr@2: A templated function that is used by a library (DLL) that requires to use
williamr@2: WSD on the emulator.
williamr@2: The function returns the PLS (Process Local Storage) object of the specified library, 
williamr@2: for the current process. If the PLS object doesn't yet exist then it is allocated, 
williamr@2: initialised, stored and returned.
williamr@2: The template type T is the type of the PLS object, and is supplied by the caller.
williamr@2: 
williamr@2: Takes as a parameter the TUid of the library DLL whose PLS is to be returned for the 
williamr@2: current process. It also takes as a parameter a pointer to a (non-leaving, non-panicing) 
williamr@2: initialisation function defined by the caller which takes a pointer to T (i.e. the 
williamr@2: PLS object) as a parameter and returns one of the system wide error codes as a TInt.
williamr@2: This parameter is optional but it should be used when necessary to ensure that if Pls() 
williamr@2: requires to create a PLS object then the object is completely initialised on its return. 
williamr@2: The initialisation function is called after the PLS object has been allocated and its 
williamr@2: constructor called if it is an instance of a class - neither the constructor nor the 
williamr@2: initialisation function should call Pls().
williamr@2: 
williamr@2: Returns a pointer to the PLS object					
williamr@2: */
williamr@2: template <typename T>
williamr@2: T* Pls(const TUid& aLibraryUid, TInt (*aInitFunc)(T*) = 0)
williamr@2: 	{
williamr@2: 	// Fetch the PLS, if it has been set
williamr@2: 	T* p = (T*) CheckPls(aLibraryUid);
williamr@2: 	if (p)
williamr@2: 		{
williamr@2: 		return p;
williamr@2: 		}
williamr@2: 	
williamr@2: 	// Obtain ownership of the mutex
williamr@2: 	TAny* mutexHandle = ObtainPlsMutex(); 
williamr@2: 			
williamr@2: 	// Check we haven't obtained the mutex from 
williamr@2: 	// another thread that has just set the same PLS!
williamr@2: 	p = (T*) CheckPls(aLibraryUid);
williamr@2: 	if (p) 
williamr@2: 		{
williamr@2: 		ReleasePlsMutex(mutexHandle);				
williamr@2: 		return p;
williamr@2: 		}
williamr@2: 	
williamr@2: 	// Allocate the memory for the PLS object
williamr@2: 	p = (T*) AllocatePls(sizeof(T));
williamr@2: 	if (!p)
williamr@2: 		{
williamr@2: 		ReleasePlsMutex(mutexHandle);
williamr@2: 		User::Panic(KVirtualAllocFailure, KErrNoMemory);
williamr@2: 		}
williamr@2: 			
williamr@2: 	// Do a placement new to construct the PLS object in the allocated memory
williamr@2: 	p = new (p) T;
williamr@2: 	
williamr@2: 	// Call the initialisation function (if one is provided)
williamr@2: 	// to complete initialisation of the PLS object
williamr@2: 	if (aInitFunc)
williamr@2: 		{
williamr@2: 		 if (((*aInitFunc)(p)) != KErrNone) 
williamr@2: 		 	{
williamr@2: 		 	 FreePls(p);			
williamr@2: 			 ReleasePlsMutex(mutexHandle);
williamr@2: 			 User::Panic(KPLSInitFailed, KErrGeneral);
williamr@2: 		 	}
williamr@2: 		}
williamr@2: 		
williamr@2: 	// Finally, call SetPls() to store the PLS object.
williamr@2: 	// NOTE: This step is last to ensure that a PLS object returned by 
williamr@2: 	// CheckPls() is completely constructed/initialised. This is important 
williamr@2: 	// to handle the scenario in which the thread that is creating the PLS 
williamr@2: 	// object is interrupted by another call to Pls() by another thread
williamr@2: 	if (SetPls(p, aLibraryUid) != KErrNone)
williamr@2: 		{
williamr@2: 		// SetPls() failed due to a size limit being reached in the wsdArray
williamr@2: 		FreePls(p);
williamr@2: 		ReleasePlsMutex(mutexHandle);
williamr@2: 		User::Panic(KWsdArrayFull, KErrNoMemory);				
williamr@2: 		}
williamr@2: 
williamr@2: 	ReleasePlsMutex(mutexHandle);		
williamr@2: 	return p;
williamr@2: 	}
williamr@2: 
williamr@2: #endif // __WINSCW__
williamr@2: 
williamr@2: #endif // __PLS_H__
williamr@2: