1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/os/ossrv/genericopenlibs/openenvcore/ewsd/inc/pls.dosc	Fri Jun 15 03:10:57 2012 +0200
     1.3 @@ -0,0 +1,32 @@
     1.4 +/** @file  ../inc/pls.h
     1.5 +@internalComponent
     1.6 +*/
     1.7 +
     1.8 +/** @fn  Pls(const TUid& aLibraryUid, TInt (*aInitFunc)(T*) = 0)
     1.9 +@return Pls() will always return a non-NULL value.
    1.10 +If Pls() fails to allocate memory, it will panic rather than returning NULL. 
    1.11 +The risk of such a panic is minimal due to the allocation of Windows OS memory for the Pls object (which is effectively unlimited) rather than memory from the Emulator.
    1.12 +
    1.13 +A templated function that is used by a library (DLL) that requires to use
    1.14 +WSD on the emulator.
    1.15 +The function returns the PLS (Process Local Storage) object of the specified library, 
    1.16 +for the current process. If the PLS object doesn't yet exist then it is allocated, 
    1.17 +initialised, stored and returned.
    1.18 +The template type T is the type of the PLS object, and is supplied by the caller.
    1.19 +
    1.20 +Takes as a parameter the TUid of the library DLL whose PLS is to be returned for the 
    1.21 +current process. It also takes as a parameter a pointer to a (non-leaving, non-panicing) 
    1.22 +initialisation function defined by the caller which takes a pointer to T (i.e. the 
    1.23 +PLS object) as a parameter and returns one of the system wide error codes as a TInt.
    1.24 +This parameter is optional but it should be used when necessary to ensure that if Pls() 
    1.25 +requires to create a PLS object then the object is completely initialised on its return. 
    1.26 +The initialisation function is called after the PLS object has been allocated and its 
    1.27 +constructor called if it is an instance of a class - neither the constructor nor the 
    1.28 +initialisation function should call Pls().
    1.29 +
    1.30 +Returns a pointer to the PLS object		
    1.31 +
    1.32 +
    1.33 +@publishedAll
    1.34 +@released
    1.35 +*/