1.1 --- a/epoc32/include/pls.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/pls.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,140 @@
1.4 -pls.h
1.5 +/*
1.6 +* Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description:
1.19 +* Name : pls.h
1.20 +* Part of : Client API for ewsd library
1.21 +* Contains the client API for using the emulator WSD library
1.22 +* Redistribution and use in source and binary forms, with or without
1.23 +* modification, are permitted provided that the following conditions are met:
1.24 +* Redistributions of source code must retain the above copyright notice, this
1.25 +* list of conditions and the following disclaimer.
1.26 +* Redistributions in binary form must reproduce the above copyright notice,
1.27 +* this list of conditions and the following disclaimer in the documentation
1.28 +* and/or other materials provided with the distribution.
1.29 +* Neither the name of the <ORGANIZATION> nor the names of its contributors
1.30 +* may be used to endorse or promote products derived from this software
1.31 +* without specific prior written permission.
1.32 +* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
1.33 +* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
1.34 +* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
1.35 +* DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
1.36 +* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
1.37 +* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
1.38 +* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
1.39 +* CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
1.40 +* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
1.41 +* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.42 +*
1.43 +*/
1.44 +
1.45 +
1.46 +
1.47 +#ifndef __PLS_H__
1.48 +#define __PLS_H__
1.49 +
1.50 +#ifdef __WINSCW__
1.51 +
1.52 +#include <ewsd.h>
1.53 +
1.54 +// Panic strings
1.55 +_LIT(KVirtualAllocFailure, "WSD VirtualAlloc() failed");
1.56 +_LIT(KPLSInitFailed, "WSD PLS init failed");
1.57 +_LIT(KWsdArrayFull, "WSD process or lib array full");
1.58 +
1.59 +/**
1.60 +A templated function that is used by a library (DLL) that requires to use
1.61 +WSD on the emulator.
1.62 +The function returns the PLS (Process Local Storage) object of the specified library,
1.63 +for the current process. If the PLS object doesn't yet exist then it is allocated,
1.64 +initialised, stored and returned.
1.65 +The template type T is the type of the PLS object, and is supplied by the caller.
1.66 +
1.67 +Takes as a parameter the TUid of the library DLL whose PLS is to be returned for the
1.68 +current process. It also takes as a parameter a pointer to a (non-leaving, non-panicing)
1.69 +initialisation function defined by the caller which takes a pointer to T (i.e. the
1.70 +PLS object) as a parameter and returns one of the system wide error codes as a TInt.
1.71 +This parameter is optional but it should be used when necessary to ensure that if Pls()
1.72 +requires to create a PLS object then the object is completely initialised on its return.
1.73 +The initialisation function is called after the PLS object has been allocated and its
1.74 +constructor called if it is an instance of a class - neither the constructor nor the
1.75 +initialisation function should call Pls().
1.76 +
1.77 +Returns a pointer to the PLS object
1.78 +*/
1.79 +template <typename T>
1.80 +T* Pls(const TUid& aLibraryUid, TInt (*aInitFunc)(T*) = 0)
1.81 + {
1.82 + // Fetch the PLS, if it has been set
1.83 + T* p = (T*) CheckPls(aLibraryUid);
1.84 + if (p)
1.85 + {
1.86 + return p;
1.87 + }
1.88 +
1.89 + // Obtain ownership of the mutex
1.90 + TAny* mutexHandle = ObtainPlsMutex();
1.91 +
1.92 + // Check we haven't obtained the mutex from
1.93 + // another thread that has just set the same PLS!
1.94 + p = (T*) CheckPls(aLibraryUid);
1.95 + if (p)
1.96 + {
1.97 + ReleasePlsMutex(mutexHandle);
1.98 + return p;
1.99 + }
1.100 +
1.101 + // Allocate the memory for the PLS object
1.102 + p = (T*) AllocatePls(sizeof(T));
1.103 + if (!p)
1.104 + {
1.105 + ReleasePlsMutex(mutexHandle);
1.106 + User::Panic(KVirtualAllocFailure, KErrNoMemory);
1.107 + }
1.108 +
1.109 + // Do a placement new to construct the PLS object in the allocated memory
1.110 + p = new (p) T;
1.111 +
1.112 + // Call the initialisation function (if one is provided)
1.113 + // to complete initialisation of the PLS object
1.114 + if (aInitFunc)
1.115 + {
1.116 + if (((*aInitFunc)(p)) != KErrNone)
1.117 + {
1.118 + FreePls(p);
1.119 + ReleasePlsMutex(mutexHandle);
1.120 + User::Panic(KPLSInitFailed, KErrGeneral);
1.121 + }
1.122 + }
1.123 +
1.124 + // Finally, call SetPls() to store the PLS object.
1.125 + // NOTE: This step is last to ensure that a PLS object returned by
1.126 + // CheckPls() is completely constructed/initialised. This is important
1.127 + // to handle the scenario in which the thread that is creating the PLS
1.128 + // object is interrupted by another call to Pls() by another thread
1.129 + if (SetPls(p, aLibraryUid) != KErrNone)
1.130 + {
1.131 + // SetPls() failed due to a size limit being reached in the wsdArray
1.132 + FreePls(p);
1.133 + ReleasePlsMutex(mutexHandle);
1.134 + User::Panic(KWsdArrayFull, KErrNoMemory);
1.135 + }
1.136 +
1.137 + ReleasePlsMutex(mutexHandle);
1.138 + return p;
1.139 + }
1.140 +
1.141 +#endif // __WINSCW__
1.142 +
1.143 +#endif // __PLS_H__
1.144 +