1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/kernelhwsrv/kernel/eka/euser/us_ksvr.cpp Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,5507 @@
1.4 +// Copyright (c) 1995-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// e32\euser\us_ksvr.cpp
1.18 +//
1.19 +//
1.20 +
1.21 +#include "us_std.h"
1.22 +#include "us_data.h"
1.23 +#include <e32svr.h>
1.24 +#include <e32uid.h>
1.25 +#include <e32ldr.h>
1.26 +
1.27 +//#define __DEBUG_IMAGE__ 1
1.28 +#if defined(__DEBUG_IMAGE__) && defined (__EPOC32__)
1.29 +#define __IF_DEBUG(t) {RDebug::t;}
1.30 +#else
1.31 +#define __IF_DEBUG(t)
1.32 +#endif
1.33 +
1.34 +//
1.35 +// class RNotifier
1.36 +//
1.37 +
1.38 +/**
1.39 +Requests the extended notifier server to start the notifier identified by
1.40 +the specified UID.
1.41 +
1.42 +The request is synchronous; the call returns when the request is complete.
1.43 +
1.44 +The notifier may not be started immediately if a higher priority notifier is
1.45 +already active. In this case, the notifier is queued until it has the highest
1.46 +priority outstanding request for the channel(s) it operates on.
1.47 +
1.48 +@param aNotifierUid The UID identifying the notifier.
1.49 +@param aBuffer Data that can be passed to the notifier; the format and meaning
1.50 + of this depends on the notifier.
1.51 +
1.52 +@return KErrNone, if successful;
1.53 + KErrNotFound, if there is no notifier matching the specified UID;
1.54 + KErrAlreadyExists, if the notifier has already been started, or has
1.55 + an outstanding start request. It may also return with one of the other
1.56 + system-wide error codes, if the notifier cannot be started by
1.57 + the server due to low memory or it leaves from its server side
1.58 + call to StartL().
1.59 +
1.60 +@see CServer
1.61 +*/
1.62 +EXPORT_C TInt RNotifier::StartNotifier(TUid aNotifierUid, const TDesC8& aBuffer)
1.63 + {
1.64 + return SendReceive(EStartNotifier, TIpcArgs(
1.65 + (TInt)aNotifierUid.iUid,
1.66 + &aBuffer,
1.67 + (TAny*)NULL // No resonse required
1.68 + ));
1.69 + }
1.70 +
1.71 +
1.72 +
1.73 +
1.74 +/**
1.75 +Requests the extended notifier server to start the notifier identified by
1.76 +the specified UID.
1.77 +
1.78 +The request is synchronous; the call returns when the request is complete.
1.79 +
1.80 +The notifier may not start immediately if a higher priority notifier is
1.81 +already active. In this case, the notifier is queued until it has the highest
1.82 +priority outstanding request for the channel(s) it operates on.
1.83 +This can also cause unexpected behaviour: the function can return
1.84 +before the notifier has been started with the added consequence that no response
1.85 +data is written.
1.86 +
1.87 +For this reason, this function has been deprecated. Instead, use
1.88 +RNotifier::StartNotifierAndGetResponse(), or if there is no need to wait for a
1.89 +response, use the two argument overload of RNotifier::StartNotifier().
1.90 +
1.91 +@param aNotifierUid The UID identifying the notifier.
1.92 +@param aBuffer Data that can be passed to the notifier; the format and meaning
1.93 + of this depends on the notifier.
1.94 +@param aResponse Response data; the format
1.95 + and meaning of this depends on the notifier.
1.96 +
1.97 +@return KErrNone, if successful;
1.98 + KErrNotFound, if there is no notifier matching the specified UID;
1.99 + KErrAlreadyExists, if the notifier has already been started, or has
1.100 + an outstanding start request. It may also return with one of the other
1.101 + system-wide error codes, if the notifier cannot be started by
1.102 + the server due to low memory or it leaves from its server side
1.103 + call to StartL().
1.104 +
1.105 +@see CServer
1.106 +
1.107 +@deprecated use RNotifier::StartNotifierAndGetResponse(), or if there is no
1.108 + need to wait for a response, use the two argument overload
1.109 + of RNotifier::StartNotifier()
1.110 +*/
1.111 +EXPORT_C TInt RNotifier::StartNotifier(TUid aNotifierUid, const TDesC8& aBuffer, TDes8& aResponse)
1.112 + {
1.113 + return SendReceive(EStartNotifier, TIpcArgs(
1.114 + (TInt)aNotifierUid.iUid,
1.115 + &aBuffer,
1.116 + &aResponse
1.117 + ));
1.118 + }
1.119 +
1.120 +/*
1.121 +This function has never been implemented on any Symbian OS version.
1.122 +It always returns KErrNotSupported.
1.123 +@publishedPartner
1.124 +@removed
1.125 +*/
1.126 +EXPORT_C TInt RNotifier::StartNotifier(TUid aNotifierDllUid,TUid aNotifierUid,const TDesC8& aBuffer,TDes8& aResponse)
1.127 + {
1.128 + return SendReceive(EStartNotifierFromSpecifiedDll, TIpcArgs(
1.129 + (TInt)aNotifierUid.iUid,
1.130 + &aBuffer,
1.131 + &aResponse,
1.132 + (TInt)aNotifierDllUid.iUid
1.133 + ));
1.134 + }
1.135 +
1.136 +/**
1.137 +Requests the extended notifier server to cancel the notifier identified by
1.138 +the specified UID.
1.139 +
1.140 +The request is synchronous; the call returns when the request is complete.
1.141 +
1.142 +Any notifier that was queued pending the completion of aNotifierUid will be
1.143 +automatically started.
1.144 +
1.145 +@param aNotifierUid The UID identifying the notifier.
1.146 +
1.147 +@return KErrNone, if successful;
1.148 + KErrNotFound, if there is no notifier matching the specified UID.
1.149 +*/
1.150 +EXPORT_C TInt RNotifier::CancelNotifier(TUid aNotifierUid)
1.151 + {
1.152 + return SendReceive(ECancelNotifier, TIpcArgs( (TInt)aNotifierUid.iUid ));
1.153 + }
1.154 +
1.155 +/**
1.156 +Requests the extended notifier server to update the active notifier identified by
1.157 +the specified UID.
1.158 +
1.159 +The request is synchronous; the call returns when the request is complete.
1.160 +
1.161 +@param aNotifierUid The UID identifying the notifier.
1.162 +@param aBuffer Data that can be passed to the notifier; the format and meaning
1.163 + of this depends on the notifier.
1.164 +@param aResponse Reserved for future use.
1.165 +
1.166 +@return KErrNone, if successful;
1.167 + KErrNotFound, if there is no notifier matching the specified UID.
1.168 +*/
1.169 +EXPORT_C TInt RNotifier::UpdateNotifier(TUid aNotifierUid, const TDesC8& aBuffer,TDes8& aResponse)
1.170 + {
1.171 + return SendReceive(EUpdateNotifier, TIpcArgs(
1.172 + (TInt)aNotifierUid.iUid,
1.173 + &aBuffer,
1.174 + &aResponse
1.175 + ));
1.176 + }
1.177 +
1.178 +/**
1.179 +Requests the extended notifier server to update the active notifier identified by
1.180 +the specified UID.
1.181 +
1.182 +This is an asynchronous request.It may be called multiple times for
1.183 +some notifier implementations; see specific notifier documentation for exact details.
1.184 +
1.185 +@param aRs The request status. On request completion, contains:
1.186 + KErrNone, if successful; otherwise, one of the other system
1.187 + wide error codes.
1.188 +@param aNotifierUid The UID identifying the notifier.
1.189 +@param aBuffer Data that can be passed to the notifier; the format and meaning
1.190 + of this depends on the notifier.
1.191 +@param aResponse Reserved for future use.
1.192 +
1.193 +*/
1.194 +EXPORT_C void RNotifier::UpdateNotifierAndGetResponse(TRequestStatus& aRs, TUid aNotifierUid, const TDesC8& aBuffer, TDes8& aResponse)
1.195 + {
1.196 + SendReceive(EUpdateNotifierAndGetResponse, TIpcArgs(
1.197 + (TInt)aNotifierUid.iUid,
1.198 + &aBuffer,
1.199 + &aResponse
1.200 + ), aRs);
1.201 + }
1.202 +
1.203 +/**
1.204 +Requests the extended notifier server to start the notifier identified by
1.205 +the specified UID.
1.206 +
1.207 +This is an asynchronous request.It may be called multiple times for
1.208 +some notifier implementations; see specific notifier documentation for exact details.
1.209 +
1.210 +@param aRs The request status. On request completion, contains:
1.211 + KErrNone, if successful; otherwise, one of the other system
1.212 + wide error codes.
1.213 +@param aNotifierUid The UID identifying the notifier.
1.214 +@param aBuffer Data that can be passed to the notifier; the format
1.215 + and meaning of this depends on the notifier.
1.216 +@param aResponse Response data; the format
1.217 + and meaning of this depends on the notifier.
1.218 +*/
1.219 +EXPORT_C void RNotifier::StartNotifierAndGetResponse(TRequestStatus& aRs,TUid aNotifierUid,const TDesC8& aBuffer,TDes8& aResponse)
1.220 + {
1.221 + SendReceive(EStartNotifierAndGetResponse, TIpcArgs(
1.222 + (TInt)aNotifierUid.iUid,
1.223 + &aBuffer,
1.224 + &aResponse
1.225 + ), aRs);
1.226 + }
1.227 +
1.228 +
1.229 +
1.230 +
1.231 +/**
1.232 +@publishedPartner
1.233 +@removed
1.234 +
1.235 +This function has never been implemented on any Symbian OS version.
1.236 +The request always completes with KErrNotSupported.
1.237 +*/
1.238 +EXPORT_C void RNotifier::StartNotifierAndGetResponse(TRequestStatus& aRs,TUid aNotifierDllUid,TUid aNotifierUid,const TDesC8& aBuffer,TDes8& aResponse)
1.239 + {
1.240 + SendReceive(EStartNotifierFromSpecifiedDllAndGetResponse, TIpcArgs(
1.241 + (TInt)aNotifierUid.iUid,
1.242 + &aBuffer,
1.243 + &aResponse,
1.244 + (TInt)aNotifierDllUid.iUid
1.245 + ), aRs);
1.246 + }
1.247 +
1.248 +
1.249 +
1.250 +
1.251 +/**
1.252 +@publishedPartner
1.253 +@removed
1.254 +
1.255 +This function has never been implemented on any Symbian OS version.
1.256 +It always returns KErrNotSupported.
1.257 +*/
1.258 +EXPORT_C TInt RNotifier::UnloadNotifiers(TUid /*aNotifierUid*/)
1.259 + {
1.260 + return KErrNotSupported;
1.261 + }
1.262 +
1.263 +
1.264 +
1.265 +
1.266 +/**
1.267 +@publishedPartner
1.268 +@removed
1.269 +
1.270 +This function has never been implemented on any Symbian OS version.
1.271 +It always returns KErrNotSupported.
1.272 +*/
1.273 +EXPORT_C TInt RNotifier::LoadNotifiers(TUid /*aNotifierUid*/)
1.274 + {
1.275 + return KErrNotSupported;
1.276 + }
1.277 +
1.278 +
1.279 +
1.280 +
1.281 +/**
1.282 +Default constructor.
1.283 +*/
1.284 +EXPORT_C RNotifier::RNotifier()
1.285 + : iButtonVal(NULL,0),
1.286 + iCombinedBuffer(NULL)
1.287 + {}
1.288 +
1.289 +
1.290 +
1.291 +
1.292 +/**
1.293 +Connects to the extended notifier server, creating a session with that server.
1.294 +Note: Notifier server is started during window server start-up sequence.
1.295 +
1.296 +The function must be called before any other function.
1.297 +
1.298 +@return KErrNone, if successful, otherwise one of the other system-wide error codes
1.299 +*/
1.300 +EXPORT_C TInt RNotifier::Connect()
1.301 + {
1.302 + return CreateSession(__NOTIFIER_NAME,TVersion(KNotifierMajorVersionNumber,KNotifierMinorVersionNumber,KNotifierBuildVersionNumber),-1);
1.303 + }
1.304 +
1.305 +
1.306 +
1.307 +
1.308 +/**
1.309 +Launches a simple two line dialog that displays two lines of text.
1.310 +
1.311 +This is an asynchronous request that completes when the dialog exits.
1.312 +
1.313 +@param aLine1 A descriptor containing the first line of text to be displayed.
1.314 +@param aLine2 A descriptor containing the second line of text to be displayed.
1.315 +@param aBut1 A descriptor containing text to be displayed in the first button.
1.316 +@param aBut2 A descriptor containing text to be displayed in the (optional) second button.
1.317 +@param aButtonVal An integer value which is set when the dialog exits. It is set to:
1.318 + 0, if the first button is selected;
1.319 + 1, if the second button is selected.
1.320 +@param aStatus The request status object. If the request completes normally, this is set to KErrNone.
1.321 +*/
1.322 +EXPORT_C void RNotifier::Notify(const TDesC& aLine1,const TDesC& aLine2,const TDesC& aBut1,const TDesC& aBut2, TInt& aButtonVal, TRequestStatus& aStatus)
1.323 + {
1.324 + const TInt requiredLengthOfCombinedBuffer=aLine1.Length()+aLine2.Length()+aBut1.Length()+aBut2.Length();
1.325 + if ((iCombinedBuffer!=NULL) && (iCombinedBuffer->Des().MaxLength()<requiredLengthOfCombinedBuffer))
1.326 + {
1.327 + delete iCombinedBuffer;
1.328 + iCombinedBuffer=NULL;
1.329 + }
1.330 + if (iCombinedBuffer==NULL)
1.331 + {
1.332 + iCombinedBuffer=HBufC::New(requiredLengthOfCombinedBuffer);
1.333 + }
1.334 + if (iCombinedBuffer==NULL)
1.335 + {
1.336 + // report the error back via the TRequestStatus
1.337 + TRequestStatus* status=&aStatus;
1.338 + User::RequestComplete(status,KErrNoMemory);
1.339 + }
1.340 + else
1.341 + {
1.342 + TPtr combinedBufferForNotify(iCombinedBuffer->Des());
1.343 + combinedBufferForNotify = aLine1;
1.344 + combinedBufferForNotify.Append(aLine2);
1.345 + combinedBufferForNotify.Append(aBut1);
1.346 + combinedBufferForNotify.Append(aBut2);
1.347 + iButtonVal.Set(REINTERPRET_CAST(TUint8*,&aButtonVal),sizeof(TInt),sizeof(TInt));
1.348 + __ASSERT_ALWAYS(((aLine1.Length()|aLine2.Length()|aBut1.Length()|aBut2.Length())&~KMaxTUint16)==0,Panic(ENotifierTextTooLong)); // check that all of the descriptor lengths are less than or equal to KMaxTUint16
1.349 + SendReceive(ENotifierNotify,TIpcArgs(&iButtonVal,iCombinedBuffer,(aLine1.Length()<<16)|aLine2.Length(),(aBut1.Length()<<16)|aBut2.Length()),aStatus);
1.350 + }
1.351 + }
1.352 +
1.353 +
1.354 +
1.355 +
1.356 +/**
1.357 +Not implemented by the server.
1.358 +*/
1.359 +EXPORT_C void RNotifier::NotifyCancel()
1.360 + {
1.361 + SendReceive(ENotifierNotifyCancel,TIpcArgs()); // ignores any returned error
1.362 + }
1.363 +
1.364 +
1.365 +
1.366 +
1.367 +/**
1.368 +Closes the notifier.
1.369 +*/
1.370 +EXPORT_C void RNotifier::Close()
1.371 + {
1.372 + delete iCombinedBuffer;
1.373 + iCombinedBuffer=NULL;
1.374 + RSessionBase::Close();
1.375 + }
1.376 +
1.377 +
1.378 +
1.379 +
1.380 +/**
1.381 +@internalAll
1.382 +*/
1.383 +EXPORT_C TInt RNotifier::InfoPrint(const TDesC& aDes)
1.384 + {
1.385 + return SendReceive(ENotifierInfoPrint, TIpcArgs(&aDes));
1.386 + }
1.387 +
1.388 +
1.389 +//
1.390 +// Class TChunkCreateInfo
1.391 +//
1.392 +
1.393 +/**
1.394 +Default constructor.
1.395 +
1.396 +This defaults the chunk to be created to be local, to have no attributes set
1.397 +and to use the default clear byte.
1.398 +
1.399 +A local chunk is private to the process creating it and is not
1.400 +intended for access by other user processes.
1.401 +*/
1.402 +EXPORT_C TChunkCreateInfo::TChunkCreateInfo() :
1.403 + // Specifing individual initialisers for members instead of using memclear
1.404 + // so that Coverity doesn't complain about uninitialised local variables in
1.405 + // calls to e.g., TChunkCreateInfo::SetPaging().
1.406 + iVersionNumber(0),
1.407 + iType(TChunkCreate::ENormal),
1.408 + iGlobal(EFalse),
1.409 + iMaxSize(0),
1.410 + iOwnerType(EOwnerProcess),
1.411 + iName(NULL),
1.412 + iInitialBottom(0),
1.413 + iInitialTop(0),
1.414 + iAttributes(TChunkCreate::EPagingUnspec),
1.415 + iClearByte(KChunkClearByteDefault)
1.416 + {
1.417 + }
1.418 +
1.419 +
1.420 +/**
1.421 +Sets the chunk to be created to have a committed region that always starts at the
1.422 +bottom of the reserved region.
1.423 +
1.424 +
1.425 +@param aSize The number of bytes committed to this chunk.
1.426 +@param aMaxSize The maximum size to which the reserved region of this chunk
1.427 + can grow.
1.428 +@see RChunk::CreateLocal()
1.429 +*/
1.430 +EXPORT_C void TChunkCreateInfo::SetNormal(TInt aInitialSize, TInt aMaxSize)
1.431 + {
1.432 + iType = TChunkCreate::ENormal | TChunkCreate::EData;
1.433 + iInitialBottom = 0;
1.434 + iInitialTop = aInitialSize;
1.435 + iMaxSize = aMaxSize;
1.436 + }
1.437 +
1.438 +
1.439 +/**
1.440 +Sets the chunk to be created to be user writable and to be marked by the kernel
1.441 +as containing code.
1.442 +This can only be set on local chunks.
1.443 +
1.444 +@param aInitialSize The number of bytes committed to this chunk.
1.445 +@param aMaxSize The maximum size to which the reserved region of this chunk
1.446 + can grow.
1.447 +@see RChunk::CreateLocalCode()
1.448 +*/
1.449 +EXPORT_C void TChunkCreateInfo::SetCode(TInt aInitialSize, TInt aMaxSize)
1.450 + {
1.451 + iType = TChunkCreate::ENormal | TChunkCreate::ECode;
1.452 + iInitialBottom = 0;
1.453 + iInitialTop = aInitialSize;
1.454 + iMaxSize = aMaxSize;
1.455 + }
1.456 +
1.457 +
1.458 +/**
1.459 +Sets the chunk to be created to have a commited region that that can be any
1.460 +contiguous subset of the reserved region.
1.461 +
1.462 +@param aInitialBottom The offset of the bottom of the new committed region
1.463 + from the base of the chunk's reserved region.
1.464 +@param aInitialTop The offset of the top of the new committed region from
1.465 + the base of the chunk's reserved region.
1.466 +@param aMaxSize The maximum size to which the reserved region of
1.467 + this chunk can grow.
1.468 +@see RChunk::CreateDoubleEndedLocal()
1.469 +*/
1.470 +EXPORT_C void TChunkCreateInfo::SetDoubleEnded(TInt aInitialBottom, TInt aInitialTop, TInt aMaxSize)
1.471 + {
1.472 + iType = TChunkCreate::EDoubleEnded | TChunkCreate::EData;
1.473 + iInitialBottom = aInitialBottom;
1.474 + iInitialTop = aInitialTop;
1.475 + iMaxSize = aMaxSize;
1.476 + }
1.477 +
1.478 +/**
1.479 +Set the chunk to be created to have a committed region consisting of an
1.480 +arbitrary set of MMU pages within the reserved region.
1.481 +
1.482 +@param aInitialBottom The offset of the bottom of the new committed region
1.483 + from the base of the chunk's reserved region.
1.484 +@param aInitialTop The offset of the top of the new committed region
1.485 + from the base of the chunk's reserved region.
1.486 +@param aMaxSize The maximum size to which the reserved region of
1.487 + this chunk can grow.
1.488 +@see RChunk::CreateDisconnectedLocal()
1.489 +*/
1.490 +EXPORT_C void TChunkCreateInfo::SetDisconnected(TInt aInitialBottom, TInt aInitialTop, TInt aMaxSize)
1.491 + {
1.492 + iType = TChunkCreate::EDisconnected | TChunkCreate::EData;
1.493 + iInitialBottom = aInitialBottom;
1.494 + iInitialTop = aInitialTop;
1.495 + iMaxSize = aMaxSize;
1.496 + }
1.497 +
1.498 +
1.499 +/**
1.500 +Sets the chunk to be created to be a thread heap chunk.
1.501 +For internal use only.
1.502 +
1.503 +@param aInitialSize The number of bytes committed to this chunk.
1.504 +@param aMaxSize The maximum size to which the reserved region of this chunk
1.505 + can grow.
1.506 +@param aName The name to be given to the chunk to be created
1.507 +@internalComponent
1.508 +*/
1.509 +void TChunkCreateInfo::SetThreadHeap(TInt aInitialSize, TInt aMaxSize, const TDesC& aName)
1.510 + {
1.511 + iType = TChunkCreate::ENormal | TChunkCreate::EData;
1.512 + iInitialBottom = 0;
1.513 + iInitialTop = aInitialSize;
1.514 + iMaxSize = aMaxSize;
1.515 + iAttributes |= TChunkCreate::ELocalNamed;
1.516 + iName = &aName;
1.517 + iOwnerType = EOwnerThread;
1.518 + }
1.519 +
1.520 +/**
1.521 +Sets the owner of the chunk to be created.
1.522 +@param aType The owner of the chunk to be created.
1.523 +*/
1.524 +EXPORT_C void TChunkCreateInfo::SetOwner(TOwnerType aType)
1.525 + {
1.526 + iOwnerType = aType;
1.527 + }
1.528 +
1.529 +/**
1.530 +Sets the chunk to be created to be global, i.e. it is potentially visible
1.531 +to all processes and is intended for access by other user processes.
1.532 +
1.533 +@param aName A reference to a descriptor containing the name to be
1.534 + assigned to the global chunk. The length of
1.535 + the descriptor must be no greater than that allowed for
1.536 + a TKName type.
1.537 +*/
1.538 +EXPORT_C void TChunkCreateInfo::SetGlobal(const TDesC& aName)
1.539 + {
1.540 + iName = &aName;
1.541 + iGlobal = ETrue;
1.542 + }
1.543 +
1.544 +/**
1.545 +Sets the byte value that all memory committed to the chunk will be cleared to.
1.546 +@param TUint8 aClearByte.
1.547 +*/
1.548 +EXPORT_C void TChunkCreateInfo::SetClearByte(TUint8 aClearByte)
1.549 + {
1.550 + iClearByte = aClearByte;
1.551 + }
1.552 +
1.553 +
1.554 +/**
1.555 +Sets the data paging attributes for the chunk to be created. Any previous calls
1.556 +to this method will be overridden for this TChunkCreateInfo object.
1.557 +
1.558 +@param aPaging The data paging attributes of the chunk to be created.
1.559 +
1.560 +@prototype
1.561 +*/
1.562 +EXPORT_C void TChunkCreateInfo::SetPaging(const TChunkPagingAtt aPaging)
1.563 + {
1.564 + __ASSERT_COMPILE(TChunkCreate::EPagingUnspec == 0);
1.565 + iAttributes &= ~TChunkCreate::EPagingMask;
1.566 + if (aPaging == EPaged)
1.567 + iAttributes |= TChunkCreate::EPaged;
1.568 + if (aPaging == EUnpaged)
1.569 + iAttributes |= TChunkCreate::EUnpaged;
1.570 + }
1.571 +
1.572 +/**
1.573 +Sets the global chunk to be created to be read only. Only the creating process
1.574 +will be able to write to it, not other processes.
1.575 +
1.576 +Read-Only chunks are currently only available on the Flexible Memory Model.
1.577 +
1.578 +Chunk must be global.
1.579 +*/
1.580 +EXPORT_C void TChunkCreateInfo::SetReadOnly()
1.581 + {
1.582 + iAttributes |= TChunkCreate::EReadOnly;
1.583 + }
1.584 +
1.585 +
1.586 +EXPORT_C void TChunkCreateInfo::SetCache(TInt aMaxSize)
1.587 + {
1.588 + iType = TChunkCreate::ECache | TChunkCreate::EData;
1.589 + iInitialBottom = 0;
1.590 + iInitialTop = 0;
1.591 + iMaxSize = aMaxSize;
1.592 + SetPaging(EUnpaged);
1.593 + }
1.594 +
1.595 +
1.596 +//
1.597 +// class RChunk
1.598 +//
1.599 +
1.600 +EXPORT_C TInt RChunk::CreateLocal(TInt aSize,TInt aMaxSize,TOwnerType aType)
1.601 +/**
1.602 +Creates a local chunk.
1.603 +
1.604 +The chunk is local to the process creating it; i.e. it is private to the process
1.605 +creating it and is not intended for access by other user processes.
1.606 +
1.607 +aMaxSize specifies the maximum size of the chunk and aSize specifies the number
1.608 +of bytes to be committed on creation of the chunk. Both values are rounded
1.609 +up to the next nearest processor page boundary value if they are not already
1.610 +on a processor page boundary.
1.611 +
1.612 +The committed region always starts at the bottom of the reserved region.
1.613 +
1.614 +By default, ownership of this chunk handle is vested in the current process.
1.615 +Ownership of the chunk handle can be vested in the current thread by passing
1.616 +EOwnerThread as the third parameter to this function.
1.617 +
1.618 +@param aSize The number of bytes committed to this chunk.
1.619 +@param aMaxSize The maximum size to which the reserved region of this chunk
1.620 + can grow.
1.621 +@param aType An enumeration whose enumerators define the ownership of this
1.622 + chunk handle. If not explicitly specified, EOwnerProcess is
1.623 + taken as default.
1.624 +
1.625 +@return KErrNone if successful, otherwise another of the system-wide error
1.626 + codes.
1.627 +
1.628 +@panic USER 99 if aMaxSize is negative.
1.629 +@panic USER 100 if aSize is negative.
1.630 +@panic USER 101 if aSize is greater than or equal to the supplied
1.631 + value of aMaxSize.
1.632 +*/
1.633 + {
1.634 + TChunkCreateInfo createInfo;
1.635 + createInfo.SetNormal(aSize, aMaxSize);
1.636 + createInfo.SetOwner(aType);
1.637 + return Create(createInfo);
1.638 + }
1.639 +
1.640 +
1.641 +
1.642 +
1.643 +EXPORT_C TInt RChunk::CreateLocalCode(TInt aSize,TInt aMaxSize,TOwnerType aType)
1.644 +/**
1.645 +Creates a user writable chunk that is marked by the kernel as containing code.
1.646 +
1.647 +The chunk is local to the process creating it, i.e. it is private to the process
1.648 +creating it and is not intended for access by other user processes.
1.649 +
1.650 +On systems using a Harvard cache, this type of chunk removes the need to flush
1.651 +the instruction cache (I-Cache) on a context switch. However, the instruction
1.652 +Translation Look-aside Buffer (ITLB) still needs to be flushed when switching
1.653 +to or from a process with one of these chunks in its address space. Systems with
1.654 +a dynamic branch predictor may also need to flush their branch target buffer when
1.655 +switching from one process using this type of chunk to another.
1.656 +
1.657 +@param aSize The number of bytes committed to this chunk.
1.658 +@param aMaxSize The maximum size to which the reserved region of this chunk
1.659 + can grow.
1.660 +@param aType An enumeration whose enumerators define the ownership of this
1.661 + chunk handle. If not explicitly specified, EOwnerProcess is
1.662 + taken as default.
1.663 +
1.664 +@return KErrNone if successful, otherwise another of the system-wide error
1.665 + codes.
1.666 +
1.667 +@panic USER 99 if aMaxSize is negative.
1.668 +@panic USER 100 if aSize is negative.
1.669 +@panic USER 101 if aSize is greater than or equal to the supplied
1.670 + value of aMaxSize.
1.671 +
1.672 +@see UserHeap::ChunkHeap
1.673 +@see User::IMB_Range
1.674 +*/
1.675 + {
1.676 + TChunkCreateInfo createInfo;
1.677 + createInfo.SetCode(aSize, aMaxSize);
1.678 + createInfo.SetOwner(aType);
1.679 + return Create(createInfo);
1.680 + }
1.681 +
1.682 +
1.683 +
1.684 +
1.685 +EXPORT_C TInt RChunk::CreateGlobal(const TDesC &aName,TInt aSize,TInt aMaxSize,TOwnerType aType)
1.686 +/**
1.687 +Creates a global chunk.
1.688 +
1.689 +The chunk is global; i.e. it is potentially visible to all processes and is
1.690 +intended for access by other user processes.
1.691 +
1.692 +aMaxSize specifies the maximum size of the chunk and aSize specifies the number
1.693 +of bytes to be committed on creation of the chunk. Both values are rounded
1.694 +up to the next nearest processor page boundary value ,if they are not already
1.695 +on a processor page boundary value.
1.696 +
1.697 +The committed region always starts at the bottom of the reserved region.
1.698 +
1.699 +The descriptor aName contains the name to be assigned to this global chunk. If
1.700 +this name is empty, the chunk will be anonymous. Anonymous chunks cannot be
1.701 +accessed by other processes unless the creator explicitly passes them a handle
1.702 +to the chunk - this can be used to transfer large amounts of data between
1.703 +processes in a secure fashion.
1.704 +
1.705 +By default, ownership of this chunk handle is vested in the current process.
1.706 +Ownership of the chunk handle can be vested in the current thread by passing
1.707 +EOwnerThread as the third parameter to this function.
1.708 +
1.709 +@param aName A reference to a descriptor containing the name to be assigned
1.710 + to this global chunk. The length of the descriptor must be no
1.711 + greater than that allowed for a TKName type.
1.712 +@param aSize The number of bytes committed to this chunk.
1.713 +@param aMaxSize The maximum size to which the reserved region of this chunk
1.714 + can grow.
1.715 +@param aType An enumeration whose enumerators define the ownership of this
1.716 + chunk handle. If not explicitly specified, EOwnerProcess is taken
1.717 + as default.
1.718 +
1.719 +@return KErrNone if successful, otherwise another of the system error codes.
1.720 +
1.721 +@panic USER 99 if aMaxSize is negative.
1.722 +@panic USER 100 if aSize is negative.
1.723 +@panic USER 101 if aSize is greater than or equal to the supplied
1.724 + value of aMaxSize.
1.725 +*/
1.726 + {
1.727 + TChunkCreateInfo createInfo;
1.728 + createInfo.SetNormal(aSize, aMaxSize);
1.729 + createInfo.SetGlobal(aName);
1.730 + createInfo.SetOwner(aType);
1.731 + return Create(createInfo);
1.732 + }
1.733 +
1.734 +
1.735 +
1.736 +
1.737 +EXPORT_C TInt RChunk::CreateDoubleEndedLocal(TInt aInitialBottom, TInt aInitialTop,TInt aMaxSize,TOwnerType aType)
1.738 +/**
1.739 +Creates a local, double ended, chunk.
1.740 +
1.741 +The chunk is local to the process creating it; i.e. it is private to
1.742 +the process creating it and is not intended for access by other
1.743 +user processes.
1.744 +
1.745 +The committed region of a double ended chunk can be any contiguous subset
1.746 +of the reserved region.
1.747 +
1.748 +aMaxSize specifies the maximum size of the chunk.
1.749 +
1.750 +The difference between aInitialTop and aInitialBottom gives the number of
1.751 +bytes to be committed, on creation of the chunk; aInitialBottom gives the
1.752 +offset of the bottom of the committed region from the base of the chunk's
1.753 +reserved region; aInitialTop gives the offset of the top of the committed
1.754 +region from the base of the chunk's reserved region.
1.755 +
1.756 +Both aInitialBottom and aInitialTop are rounded up to the next nearest
1.757 +processor page boundary value, if they are not already on
1.758 +a processor page boundary value.
1.759 +
1.760 +By default, ownership of this chunk handle is vested in the current process.
1.761 +Ownership of the chunk handle can be vested in the current thread by passing
1.762 +EOwnerThread as the third parameter to this function.
1.763 +
1.764 +Note that:
1.765 +
1.766 +1. the lowest valid address in a double ended chunk is the sum of the base of
1.767 + the chunk's reserved region plus the adjusted value of aInitialBottom
1.768 +
1.769 +2. the highest valid address in a double ended chunk is the the sum of the base
1.770 + of the chunk's reserved region plus the adjusted value of aInitialTop - 1.
1.771 +
1.772 +@param aInitialBottom The offset of the bottom of the new committed region
1.773 + from the base of the chunk's reserved region.
1.774 +@param aInitialTop The offset of the top of the new committed region from
1.775 + the base of the chunk's reserved region.
1.776 +@param aMaxSize The maximum size to which the reserved region of
1.777 + this chunk can grow.
1.778 +@param aType An enumeration whose enumerators define the ownership of
1.779 + this chunk handle. If not explicitly specified,
1.780 + EOwnerProcess is taken as default.
1.781 +
1.782 +@return KErrNone if successful, otherwise another of the system error codes.
1.783 +
1.784 +@panic USER 99 if aMaxSize is negative.
1.785 +@panic USER 120 if aInitialBottom is negative.
1.786 +@panic USER 121 if aInitialTop is negative.
1.787 +@panic USER 122 if aInitialBottom is greater than the supplied value
1.788 + of aInitialTop.
1.789 +@panic USER 123 if aInitialTop is greater than the supplied value of aMaxSize.
1.790 +*/
1.791 + {
1.792 + TChunkCreateInfo createInfo;
1.793 + createInfo.SetDoubleEnded(aInitialBottom, aInitialTop, aMaxSize);
1.794 + createInfo.SetOwner(aType);
1.795 + return Create(createInfo);
1.796 + }
1.797 +
1.798 +
1.799 +
1.800 +
1.801 +EXPORT_C TInt RChunk::CreateDoubleEndedGlobal(const TDesC &aName,TInt aInitialBottom,TInt aInitialTop,TInt aMaxSize,TOwnerType aType)
1.802 +/**
1.803 +Creates a global, double ended, chunk.
1.804 +
1.805 +The chunk is global; i.e. it is visible to all processes and is intended
1.806 +for access by other user processes.
1.807 +
1.808 +The committed region of a double ended chunk can be any contiguous subset
1.809 +of the reserved region.
1.810 +
1.811 +aMaxSize specifies the maximum size of the chunk.
1.812 +
1.813 +The difference between aInitialTop and aInitialBottom gives the number of
1.814 +bytes to be committed, on creation of the chunk; aInitialBottom gives the
1.815 +offset of the bottom of the committed region from the base of the chunk's
1.816 +reserved region; aInitialTop gives the offset of the top of the committed
1.817 +region from the base of the chunk's reserved region.
1.818 +
1.819 +Both aInitialBottom and aInitialTop are rounded up to the next nearest
1.820 +processor page boundary value, if they are not already on a processor page
1.821 +boundary value.
1.822 +
1.823 +The descriptor aName contains the name to be assigned to this global chunk.
1.824 +
1.825 +By default, ownership of this chunk handle is vested in the current process.
1.826 +Ownership of the chunk handle can be vested in the current thread by passing
1.827 +EOwnerThread as the third parameter to this function.
1.828 +
1.829 +Note that:
1.830 +
1.831 +1. the lowest valid address in a double ended chunk is the sum of the base of
1.832 + the chunk's reserved region plus the adjusted value of aInitialBottom
1.833 +
1.834 +2. the highest valid address in a double ended chunk is the the sum of the base
1.835 + of the chunk's reserved region plus the adjusted value of aInitialTop - 1.
1.836 +
1.837 +@param aName A reference to a descriptor containing the name to be
1.838 + assigned to this global chunk. The length of
1.839 + the descriptor must be no greater than that allowed for
1.840 + a TKName type.
1.841 +@param aInitialBottom The offset of the bottom of the new committed region
1.842 + from the base of the chunk's reserved region.
1.843 +@param aInitialTop The offset of the top of the new committed region from
1.844 + the base of the chunk's reserved region.
1.845 +@param aMaxSize The maximum size to which the reserved region of
1.846 + this chunk can grow.
1.847 +@param aType An enumeration whose enumerators define the ownership of
1.848 + this chunk handle. If not explicitly specified,
1.849 + EOwnerProcess is taken as default.
1.850 +
1.851 +@return KErrNone if successful, otherwise another of the system error codes.
1.852 +
1.853 +@panic USER 99 if aMaxSize is negative.
1.854 +@panic USER 120 if aInitialBottom is negative.
1.855 +@panic USER 121 if aInitialTop is negative.
1.856 +@panic USER 122 if aInitialBottom is greater than the supplied value
1.857 + of aInitialTop.
1.858 +@panic USER 123 if aInitialTop is greater than the supplied value of aMaxSize.
1.859 +@panic USER 163 if aName is empty.
1.860 +*/
1.861 + {
1.862 + TChunkCreateInfo createInfo;
1.863 + createInfo.SetDoubleEnded(aInitialBottom, aInitialTop, aMaxSize);
1.864 + createInfo.SetGlobal(aName);
1.865 + createInfo.SetOwner(aType);
1.866 + return Create(createInfo);
1.867 + }
1.868 +
1.869 +
1.870 +
1.871 +
1.872 +EXPORT_C TInt RChunk::CreateDisconnectedLocal(TInt aInitialBottom, TInt aInitialTop,TInt aMaxSize,TOwnerType aType)
1.873 +/**
1.874 +Creates a local, disconnected chunk.
1.875 +
1.876 +The chunk is local to the process creating it; i.e. it is private to
1.877 +the process creating it and is not intended for access by other
1.878 +user processes.
1.879 +
1.880 +A disconnected chunk has a committed region consisting of an arbitrary set
1.881 +of MMU pages within the reserved region, i.e. each page-sized address range
1.882 +within the reserved region which begins on a page boundary may be committed
1.883 +independently.
1.884 +
1.885 +aMaxSize specifies the maximum size of the chunk.
1.886 +
1.887 +The difference between aInitialTop and aInitialBottom gives the number of
1.888 +bytes to be committed, on creation of the chunk; aInitialBottom gives the
1.889 +offset of the bottom of the committed region from the base of the chunk's
1.890 +reserved region; aInitialTop gives the offset of the top of the committed
1.891 +region from the base of the chunk's reserved region.
1.892 +
1.893 +Both aInitialBottom and aInitialTop are rounded up to the next nearest
1.894 +processor page boundary value, if they are not already on
1.895 +a processor page boundary value.
1.896 +
1.897 +By default, ownership of this chunk handle is vested in the current process.
1.898 +Ownership of the chunk handle can be vested in the current thread by passing
1.899 +EOwnerThread as the third parameter to this function.
1.900 +
1.901 +@param aInitialBottom The offset of the bottom of the new committed region
1.902 + from the base of the chunk's reserved region.
1.903 +@param aInitialTop The offset of the top of the new committed region from
1.904 + the base of the chunk's reserved region.
1.905 +@param aMaxSize The maximum size to which the reserved region of
1.906 + this chunk can grow.
1.907 +@param aType An enumeration whose enumerators define the ownership of
1.908 + this chunk handle. If not explicitly specified,
1.909 + EOwnerProcess is taken as default.
1.910 +
1.911 +@return KErrNone if successful, otherwise another of the system error codes.
1.912 +
1.913 +@panic USER 99 if aMaxSize is negative.
1.914 +@panic USER 120 if aInitialBottom is negative.
1.915 +@panic USER 121 if aInitialTop is negative.
1.916 +@panic USER 122 if aInitialBottom is greater than the supplied value
1.917 + of aInitialTop.
1.918 +@panic USER 123 if aInitialTop is greater than the supplied value of aMaxSize.
1.919 +*/
1.920 + {
1.921 + TChunkCreateInfo createInfo;
1.922 + createInfo.SetDisconnected(aInitialBottom, aInitialTop, aMaxSize);
1.923 + createInfo.SetOwner(aType);
1.924 + return Create(createInfo);
1.925 + }
1.926 +
1.927 +
1.928 +
1.929 +
1.930 +EXPORT_C TInt RChunk::CreateDisconnectedGlobal(const TDesC &aName,TInt aInitialBottom,TInt aInitialTop,TInt aMaxSize,TOwnerType aType)
1.931 +/**
1.932 +Creates a global, disconnected, chunk.
1.933 +
1.934 +The chunk is global; i.e. it is visible to all processes and is intended
1.935 +for access by other user processes.
1.936 +
1.937 +A disconnected chunk has a committed region consisting of an arbitrary set
1.938 +of MMU pages within the reserved region, i.e. each page-sized address range
1.939 +within the reserved region which begins on a page boundary may be committed
1.940 +independently.
1.941 +
1.942 +aMaxSize specifies the maximum size of the chunk.
1.943 +
1.944 +The difference between aInitialTop and aInitialBottom gives the number of
1.945 +bytes to be committed, on creation of the chunk; aInitialBottom gives the
1.946 +offset of the bottom of the committed region from the base of the chunk's
1.947 +reserved region; aInitialTop gives the offset of the top of the committed
1.948 +region from the base of the chunk's reserved region.
1.949 +
1.950 +Both aInitialBottom and aInitialTop are rounded up to the next nearest
1.951 +processor page boundary value, if they are not already on a processor page
1.952 +boundary value.
1.953 +
1.954 +The descriptor aName contains the name to be assigned to this global chunk.
1.955 +
1.956 +By default, ownership of this chunk handle is vested in the current process.
1.957 +Ownership of the chunk handle can be vested in the current thread by passing
1.958 +EOwnerThread as the third parameter to this function.
1.959 +
1.960 +@param aName A reference to a descriptor containing the name to be
1.961 + assigned to this global chunk. The length of
1.962 + the descriptor must be no greater than that allowed for
1.963 + a TKName type.
1.964 +@param aInitialBottom The offset of the bottom of the new committed region
1.965 + from the base of the chunk's reserved region.
1.966 +@param aInitialTop The offset of the top of the new committed region from
1.967 + the base of the chunk's reserved region.
1.968 +@param aMaxSize The maximum size to which the reserved region of
1.969 + this chunk can grow.
1.970 +@param aType An enumeration whose enumerators define the ownership of
1.971 + this chunk handle. If not explicitly specified,
1.972 + EOwnerProcess is taken as default.
1.973 +
1.974 +@return KErrNone if successful, otherwise another of the system error codes.
1.975 +
1.976 +@panic USER 99 if aMaxSize is negative.
1.977 +@panic USER 120 if aInitialBottom is negative.
1.978 +@panic USER 121 if aInitialTop is negative.
1.979 +@panic USER 122 if aInitialBottom is greater than the supplied value
1.980 + of aInitialTop.
1.981 +@panic USER 123 if aInitialTop is greater than the supplied value of aMaxSize.
1.982 +*/
1.983 + {
1.984 + TChunkCreateInfo createInfo;
1.985 + createInfo.SetDisconnected(aInitialBottom, aInitialTop, aMaxSize);
1.986 + createInfo.SetGlobal(aName);
1.987 + createInfo.SetOwner(aType);
1.988 + return Create(createInfo);
1.989 + }
1.990 +
1.991 +
1.992 +/**
1.993 +Creates a chunk of the type specified by the parameter aCreateInfo.
1.994 +
1.995 +@param aCreate A reference to a TChunkCreateInfo object specifying the type of
1.996 + chunk to create.
1.997 +
1.998 +@return KErrNone on success, otherwise on of the system wide error codes.
1.999 +
1.1000 +@panic USER 99 if the specified maximum size is negative.
1.1001 +@panic USER 120 if any specified initial bottom is negative.
1.1002 +@panic USER 121 if any specified initial top is negative.
1.1003 +@panic USER 122 if any specified initial bottom is greater than the supplied value
1.1004 + for the intial top.
1.1005 +@panic USER 123 if any specified initial top is greater than the supplied value for the maximum size.
1.1006 +@panic USER 214 if any of the specified attributes is invalid.
1.1007 +@panic USER 215 if the version number of aCreateInfo is invalid.
1.1008 +*/
1.1009 +EXPORT_C TInt RChunk::Create(TChunkCreateInfo& aCreateInfo)
1.1010 + {
1.1011 + // Verify the version number of TChunkCreateInfo is supported
1.1012 + __ASSERT_ALWAYS(aCreateInfo.iVersionNumber < TChunkCreateInfo::ESupportedVersions,
1.1013 + Panic(EChkCreateInvalidVersion));
1.1014 +
1.1015 + TUint mapping = aCreateInfo.iType & ~TChunkCreate::ECode;
1.1016 + TBool shouldBeNamed = aCreateInfo.iGlobal ||
1.1017 + (aCreateInfo.iAttributes & TChunkCreate::ELocalNamed);
1.1018 + __ASSERT_ALWAYS(mapping <= (TUint)TChunkCreate::ECache, Panic(EChkCreateInvalidType));
1.1019 + __ASSERT_ALWAYS(!(aCreateInfo.iType & TChunkCreate::ECode) || !aCreateInfo.iGlobal,
1.1020 + Panic(EChkCreateInvalidType));
1.1021 + __ASSERT_ALWAYS((!shouldBeNamed && aCreateInfo.iName == NULL) ||
1.1022 + (shouldBeNamed && aCreateInfo.iName),
1.1023 + Panic(EChkCreateInvalidName));
1.1024 + __ASSERT_ALWAYS(aCreateInfo.iMaxSize >= 0, Panic(EChkCreateMaxSizeNegative));
1.1025 + __ASSERT_ALWAYS(!(aCreateInfo.iAttributes & ~TChunkCreate::EChunkCreateAttMask), Panic(EChkCreateInvalidAttribute));
1.1026 + if(mapping == TChunkCreate::ENormal)
1.1027 + {
1.1028 + // 'normal' chunks have different semantics for the meanings of
1.1029 + // aInitialBottom and aInitialTop
1.1030 + __ASSERT_ALWAYS(!aCreateInfo.iInitialBottom, Panic(EChkCreateInvalidBottom));
1.1031 + __ASSERT_ALWAYS(aCreateInfo.iInitialTop >= 0, Panic(EChkCreateSizeNotPositive));
1.1032 + __ASSERT_ALWAYS(aCreateInfo.iInitialTop <= aCreateInfo.iMaxSize, Panic(EChkCreateMaxLessThanMin));
1.1033 + }
1.1034 + else
1.1035 + {
1.1036 + __ASSERT_ALWAYS(aCreateInfo.iInitialBottom >= 0, Panic(EChkCreateBottomNegative));
1.1037 + __ASSERT_ALWAYS(aCreateInfo.iInitialTop >= 0, Panic(EChkCreateTopNegative));
1.1038 + __ASSERT_ALWAYS(aCreateInfo.iInitialTop >= aCreateInfo.iInitialBottom, Panic(EChkCreateTopLessThanBottom));
1.1039 + __ASSERT_ALWAYS(aCreateInfo.iInitialTop <= aCreateInfo.iMaxSize, Panic(EChkCreateTopBiggerThanMax));
1.1040 + }
1.1041 +
1.1042 + TChunkCreate info;
1.1043 + info.iAtt = aCreateInfo.iAttributes | (TUint)aCreateInfo.iType;
1.1044 + info.iAtt |= (aCreateInfo.iGlobal)? TChunkCreate::EGlobal : TChunkCreate::ELocal; // Add the global attribute
1.1045 + info.iForceFixed = EFalse;
1.1046 + info.iInitialBottom = aCreateInfo.iInitialBottom;
1.1047 + info.iInitialTop = aCreateInfo.iInitialTop;
1.1048 + info.iMaxSize = aCreateInfo.iMaxSize;
1.1049 + info.iClearByte = aCreateInfo.iClearByte;
1.1050 +
1.1051 + TDesC8* ptrName = NULL;
1.1052 + TBuf8<KMaxKernelName> name8;
1.1053 + if(aCreateInfo.iName)
1.1054 + {
1.1055 + TInt r = User::ValidateName(*aCreateInfo.iName);
1.1056 + if(KErrNone!=r)
1.1057 + return r;
1.1058 + name8.Copy(*aCreateInfo.iName);
1.1059 + ptrName = &name8;
1.1060 + }
1.1061 +
1.1062 + return SetReturnedHandle(Exec::ChunkCreate(aCreateInfo.iOwnerType, ptrName, info),*this);
1.1063 + }
1.1064 +
1.1065 +
1.1066 +EXPORT_C TInt RChunk::OpenGlobal(const TDesC &aName,TBool isReadOnly,TOwnerType aType)
1.1067 +/**
1.1068 +Opens a handle to a specific named global chunk.
1.1069 +
1.1070 +Full read/write access can be allowed or access can be limited to read only.
1.1071 +
1.1072 +By default, ownership of this process handle is vested in the current process,
1.1073 +but can be vested in the current thread by passing EOwnerThread as the second
1.1074 +parameter to this function.
1.1075 +
1.1076 +@param aName A reference to the descriptor containing the name of
1.1077 + the chunk to be opened.
1.1078 +@param isReadOnly This is currently not implemented and setting it to ETrue
1.1079 + will have no effect.
1.1080 + (Intended implementation will be as below:
1.1081 + Defines the type of access to the chunk: Specify ETrue if
1.1082 + access is limited to read only, otherwise specify EFalse
1.1083 + for full read/write access.)
1.1084 +@param aType An enumeration whose enumerators define ownership of
1.1085 + this chunk handle. If not explicitly specified,
1.1086 + EOwnerProcess is taken as default.
1.1087 +
1.1088 +@return KErrNone if successful, otherwise another of the system error codes.
1.1089 +*/
1.1090 + {
1.1091 + (void) isReadOnly; // This is not currently used
1.1092 + return OpenByName(aName,aType,EChunk);
1.1093 + }
1.1094 +
1.1095 +
1.1096 +
1.1097 +
1.1098 +/**
1.1099 +Opens a handle to a chunk using a handle number sent by a client
1.1100 +to a server.
1.1101 +
1.1102 +This function is called by the server.
1.1103 +
1.1104 +@param aMessage The message pointer.
1.1105 +@param aParam An index specifying which of the four message arguments
1.1106 + contains the handle number.
1.1107 +@param isReadOnly This is currently not implemented and setting it to ETrue
1.1108 + will have no effect.
1.1109 + (Intended implementation will be as below:
1.1110 + Defines the type of access to the chunk: Specify ETrue if
1.1111 + access is limited to read only, otherwise specify EFalse
1.1112 + for full read/write access.)
1.1113 +@param aType An enumeration whose enumerators define the ownership of this
1.1114 + chunk handle. If not explicitly specified, EOwnerProcess is
1.1115 + taken as default.
1.1116 +
1.1117 +@return KErrNone, if successful;
1.1118 + KErrArgument, if the value of aParam is outside the range 0-3;
1.1119 + KErrBadHandle, if not a valid handle;
1.1120 + otherwise one of the other system-wide error codes.
1.1121 +*/
1.1122 +EXPORT_C TInt RChunk::Open(RMessagePtr2 aMessage,TInt aParam,TBool isReadOnly,TOwnerType aType)
1.1123 + {
1.1124 + (void) isReadOnly; // This is not currently used
1.1125 + return SetReturnedHandle(Exec::MessageOpenObject(aMessage.Handle(),EChunk,aParam,aType));
1.1126 + }
1.1127 +
1.1128 +
1.1129 +
1.1130 +
1.1131 +/**
1.1132 +Opens a handle to a chunk using a handle number passed as an
1.1133 +environment data item to the child process during the creation of
1.1134 +that child process.
1.1135 +
1.1136 +Note that this function can only be called successfully once.
1.1137 +
1.1138 +@param aArgumentIndex An index that identifies the slot in the process
1.1139 + environment data that contains the handle number. This is
1.1140 + a value relative to zero, i.e. 0 is the first item/slot.
1.1141 + This can range from 0 to 15.
1.1142 +
1.1143 +@param aOwnerType An enumeration whose enumerators define the ownership of
1.1144 + this chunk handle. If not explicitly specified,
1.1145 + EOwnerProcess is taken as default.
1.1146 +
1.1147 +@return KErrNone, if successful;
1.1148 + KErrNotFound, if the slot indicated by aArgumentIndex is empty;
1.1149 + KErrArgument, if the slot does not contain a Semaphore handle;
1.1150 + otherwise one of the other system-wide error codes.
1.1151 +
1.1152 +@see RProcess::SetParameter()
1.1153 +*/
1.1154 +EXPORT_C TInt RChunk::Open(TInt aArgumentIndex, TOwnerType aOwnerType)
1.1155 + {
1.1156 + return SetReturnedHandle(Exec::ProcessGetHandleParameter(aArgumentIndex, EChunk, aOwnerType));
1.1157 + }
1.1158 +
1.1159 +
1.1160 +
1.1161 +
1.1162 +
1.1163 +EXPORT_C TInt RChunk::SetRestrictions(TUint aFlags)
1.1164 +/**
1.1165 +Sets or removes restrictions on the ability of the chunk to change.
1.1166 +
1.1167 +For example, to adjust, commit etc
1.1168 +
1.1169 +@param aFlags One of the values defined by TRestrictions.
1.1170 +
1.1171 +@return KErrNone if successful, otherwise another of the system error codes.
1.1172 +
1.1173 +@see RChunk::TRestrictions()
1.1174 +*/
1.1175 + {
1.1176 + return Exec::ChunkSetRestrictions(iHandle,aFlags);
1.1177 + }
1.1178 +
1.1179 +
1.1180 +
1.1181 +
1.1182 +EXPORT_C TInt RChunk::Adjust(TInt aNewSize) const
1.1183 +/**
1.1184 +Changes the number of bytes committed to the chunk.
1.1185 +
1.1186 +This value is always rounded up to the next nearest processor page boundary.
1.1187 +
1.1188 +@param aNewSize The number of bytes to be committed to this chunk.
1.1189 +
1.1190 +@return KErrNone if successful, otherwise another of the system error codes.
1.1191 +
1.1192 +@panic USER 102 if aNewSize is negative.
1.1193 +*/
1.1194 + {
1.1195 +
1.1196 + __ASSERT_ALWAYS(aNewSize>=0,Panic(EChkAdjustNewSizeNegative));
1.1197 + return Exec::ChunkAdjust(iHandle,EChunkAdjust,aNewSize,0);
1.1198 + }
1.1199 +
1.1200 +
1.1201 +
1.1202 +
1.1203 +EXPORT_C TInt RChunk::AdjustDoubleEnded(TInt aBottom, TInt aTop) const
1.1204 +/**
1.1205 +Changes the number of bytes and the position of this double ended
1.1206 +chunk's committed region.
1.1207 +
1.1208 +The difference between aTop and aBottom gives the new size of the committed
1.1209 +region; aBottom gives the offset of the bottom of the committed region from
1.1210 +the base of the chunk's reserved region.
1.1211 +
1.1212 +Both aBottom and aTop are rounded up to the next nearest processor
1.1213 +page boundary.
1.1214 +
1.1215 +The function fails if this chunk is not a double ended chunk; for a standard
1.1216 +chunk, use the Adjust() function.
1.1217 +
1.1218 +Note that if the initial and final committed regions intersect, the contents
1.1219 +of the intersection are unchanged. Other parts of the committed region have
1.1220 +undefined contents.
1.1221 +
1.1222 +Note also that:
1.1223 +
1.1224 +1. the lowest valid address in a double ended chunk is the sum of the base of
1.1225 + the chunk's reserved region plus the adjusted value of aBottom
1.1226 +
1.1227 +2. the highest valid address in a double ended chunk is the the sum of the base
1.1228 + of the chunk's reserved region plus the adjusted value of aTop - 1.
1.1229 +
1.1230 +@param aBottom The offset from the base of the chunk of the bottom of the
1.1231 + committed region.
1.1232 +@param aTop The offset from the base of the chunk of the top of the committed
1.1233 + region.
1.1234 +
1.1235 +@return KErrNone if successful, otherwise another of the system error codes.
1.1236 +
1.1237 +@panic USER 124 if aBottom is negative.
1.1238 +@panic USER 125 if aTop is negative.
1.1239 +@panic USER 126 if aBottom is greater than the supplied value of aTop.
1.1240 +*/
1.1241 + {
1.1242 + __ASSERT_ALWAYS(aBottom>=0,Panic(EChkAdjustBottomNegative));
1.1243 + __ASSERT_ALWAYS(aTop>=0,Panic(EChkAdjustTopNegative));
1.1244 + __ASSERT_ALWAYS(aTop>=aBottom,Panic(EChkAdjustTopLessThanBottom));
1.1245 + return Exec::ChunkAdjust(iHandle,EChunkAdjustDoubleEnded,aBottom,aTop);
1.1246 + }
1.1247 +
1.1248 +
1.1249 +
1.1250 +
1.1251 +EXPORT_C TInt RChunk::Commit(TInt aOffset, TInt aSize) const
1.1252 +/**
1.1253 +Commits memory to a disconnected chunk.
1.1254 +
1.1255 +Memory is committed in blocks of the MMU page size.
1.1256 +E.g. Commit(pageSize-1,2) which asks for the last byte of the first page
1.1257 +and the first byte of the second page and will result in the first 2 pages
1.1258 +in the chunk being committed.
1.1259 +For this reason it is best to only use values for aOffset and aSize which
1.1260 +are multiples of the MMU page size. This size can be obtained with the
1.1261 +following code.
1.1262 +@code
1.1263 +TInt pageSize;
1.1264 +HAL::Get(HAL::EMemoryPageSize,pageSize)
1.1265 +@endcode
1.1266 +
1.1267 +@param aOffset The offset of the committed region from the base of the chunk's
1.1268 + reserved region.
1.1269 +@param aSize The size of the committed region.
1.1270 +
1.1271 +@return KErrNone if successful, otherwise another of the system error codes.
1.1272 +
1.1273 +@panic USER 157 if anOffset is negative.
1.1274 +@panic USER 158 if aSize is negative.
1.1275 +*/
1.1276 + {
1.1277 + __ASSERT_ALWAYS(aOffset>=0,Panic(EChkCommitOffsetNegative));
1.1278 + __ASSERT_ALWAYS(aSize>=0,Panic(EChkCommitSizeNegative));
1.1279 + return Exec::ChunkAdjust(iHandle,EChunkCommit,aOffset,aSize);
1.1280 + }
1.1281 +
1.1282 +
1.1283 +
1.1284 +
1.1285 +EXPORT_C TInt RChunk::Allocate(TInt aSize) const
1.1286 +/**
1.1287 +Allocates and commits to a disconnected chunk.
1.1288 +
1.1289 +@param aSize The size of the committed region.
1.1290 +
1.1291 +@panic USER 159 if aSize is negative.
1.1292 +*/
1.1293 + {
1.1294 + __ASSERT_ALWAYS(aSize>=0,Panic(EChkAllocateSizeNegative));
1.1295 + return Exec::ChunkAdjust(iHandle,EChunkAllocate,aSize,0);
1.1296 + }
1.1297 +
1.1298 +
1.1299 +
1.1300 +
1.1301 +EXPORT_C TInt RChunk::Decommit(TInt aOffset, TInt aSize) const
1.1302 +/**
1.1303 +Decommits memory from a disconnected chunk.
1.1304 +
1.1305 +Memory is decommitted in blocks of the MMU page size.
1.1306 +E.g. Decommit(pageSize-1,2) which asks for the last byte of the first page
1.1307 +and the first byte of the second page and will result in the first 2 pages
1.1308 +in the chunk being decommitted.
1.1309 +For this reason it is best to only use values for aOffset and aSize which
1.1310 +are multiples of the MMU page size. This size can be obtained with the
1.1311 +following code.
1.1312 +@code
1.1313 +TInt pageSize;
1.1314 +HAL::Get(HAL::EMemoryPageSize,pageSize)
1.1315 +@endcode
1.1316 +
1.1317 +@param aOffset The offset of the committed region from the base of the chunk's
1.1318 + reserved region;
1.1319 +@param aSize The size of the committed region.
1.1320 +
1.1321 +@return KErrNone if successful, otherwise another of the system error codes.
1.1322 +
1.1323 +@panic USER 160 if anOffset is negative.
1.1324 +@panic USER 161 if aSize is negative.
1.1325 +*/
1.1326 + {
1.1327 + __ASSERT_ALWAYS(aOffset>=0,Panic(EChkDecommitOffsetNegative));
1.1328 + __ASSERT_ALWAYS(aSize>=0,Panic(EChkDecommitSizeNegative));
1.1329 + return Exec::ChunkAdjust(iHandle,EChunkDecommit,aOffset,aSize);
1.1330 + }
1.1331 +
1.1332 +
1.1333 +/* THIS IS A DELIBERATE NON DOXGEN STYLE TAG TO EXCLUDE THIS DOC FROM AUTO GENERATED DOCS
1.1334 +
1.1335 +Unlocks previously committed memory in a disconnected chunk.
1.1336 +
1.1337 +Unlocked memory is an intermediate state between committed and decommitted.
1.1338 +Whilst in this state, the memory must not be accessed in any way, and the
1.1339 +system is free to reclaim this RAM for other purposes, (it counts as free
1.1340 +system memory). A program may attempt to relock the memory with #Lock which,
1.1341 +when it succeeds, returns it to the committed state with its contents unchanged.
1.1342 +
1.1343 +This is intended for use in the implementation of memory caches for data
1.1344 +which can be regenerated from other sources. I.e. in situations when the
1.1345 +loss of cache contents is not a fatal condition.
1.1346 +
1.1347 +#Unlock may be used on memory which is already unlocked, in which case the memory
1.1348 +state is left unaltered. Attempting to unlock memory which is decommitted results
1.1349 +in an error.
1.1350 +
1.1351 +Unlocked memory may decommitted with #Decommit.
1.1352 +
1.1353 +Memory is unlocked in blocks of the MMU page size.
1.1354 +E.g. Unlock(pageSize-1,2) which asks for the last byte of the first page
1.1355 +and the first byte of the second page and will result in the first 2 pages
1.1356 +in the chunk being unlocked.
1.1357 +For this reason it is best to only use values for aOffset and aSize which
1.1358 +are multiples of the MMU page size. This size can be obtained with the
1.1359 +following code.
1.1360 +@code
1.1361 +TInt pageSize;
1.1362 +HAL::Get(HAL::EMemoryPageSize,pageSize)
1.1363 +@endcode
1.1364 +
1.1365 +@param aOffset The offset of the committed region from the base of the chunk's
1.1366 + reserved region;
1.1367 +@param aSize The size of the committed region.
1.1368 +
1.1369 +@return KErrNone if successful, otherwise another of the system error codes.
1.1370 +
1.1371 +@panic USER 160 if anOffset is negative.
1.1372 +@panic USER 161 if aSize is negative.
1.1373 +
1.1374 +@see RChunk::Lock
1.1375 +
1.1376 +@internalTechnology
1.1377 +*/
1.1378 +EXPORT_C TInt RChunk::Unlock(TInt aOffset, TInt aSize)
1.1379 + {
1.1380 + __ASSERT_ALWAYS(aOffset>=0,Panic(EChkDecommitOffsetNegative));
1.1381 + __ASSERT_ALWAYS(aSize>=0,Panic(EChkDecommitSizeNegative));
1.1382 + return Exec::ChunkAdjust(iHandle,EChunkUnlock,aOffset,aSize);
1.1383 + }
1.1384 +
1.1385 +/* THIS IS A DELIBERATE NON DOXGEN STYLE TAG TO EXCLUDE THIS DOC FROM AUTO GENERATED DOCS
1.1386 +
1.1387 +Locks memory in a disconnected chunk.
1.1388 +
1.1389 +This attempts to reverse the action of #Unlock and return memory to the committed
1.1390 +state. If any RAM in the region had been previously reclaimed by the system,
1.1391 +then this function fails with KErrNotFound and the whole region is decommited.
1.1392 +
1.1393 +#Lock may be used on memory which is already committed, in which case the memory
1.1394 +state is left unaltered. Attempting to lock memory which is decommitted results in an
1.1395 +error.
1.1396 +
1.1397 +Memory is locked in blocks of the MMU page size.
1.1398 +E.g. Lock(pageSize-1,2) which asks for the last byte of the first page
1.1399 +and the first byte of the second page and will result in the first 2 pages
1.1400 +in the chunk being locked.
1.1401 +For this reason it is best to only use values for aOffset and aSize which
1.1402 +are multiples of the MMU page size. This size can be obtained with the
1.1403 +following code.
1.1404 +@code
1.1405 +TInt pageSize;
1.1406 +HAL::Get(HAL::EMemoryPageSize,pageSize)
1.1407 +@endcode
1.1408 +
1.1409 +@param aOffset The offset of the unlocked region from the base of the chunk's
1.1410 + reserved region.
1.1411 +@param aSize The size of the unlocked region.
1.1412 +
1.1413 +@return KErrNone if successful, otherwise another of the system error codes.
1.1414 +
1.1415 +@panic USER 160 if anOffset is negative.
1.1416 +@panic USER 161 if aSize is negative.
1.1417 +
1.1418 +@see RChunk::Unlock
1.1419 +
1.1420 +@internalTechnology
1.1421 +*/
1.1422 +EXPORT_C TInt RChunk::Lock(TInt aOffset, TInt aSize)
1.1423 + {
1.1424 + __ASSERT_ALWAYS(aOffset>=0,Panic(EChkDecommitOffsetNegative));
1.1425 + __ASSERT_ALWAYS(aSize>=0,Panic(EChkDecommitSizeNegative));
1.1426 + return Exec::ChunkAdjust(iHandle,EChunkLock,aOffset,aSize);
1.1427 + }
1.1428 +
1.1429 +
1.1430 +/**
1.1431 +This can be used to determine whether the data for the chunk is demand paged
1.1432 +or not.
1.1433 +
1.1434 +@return ETrue if the data for the chunk is demand paged, EFalse otherwise.
1.1435 +*/
1.1436 +EXPORT_C TBool RChunk::IsPaged() const
1.1437 + {
1.1438 + return Exec::ChunkIsPaged(iHandle);
1.1439 + }
1.1440 +
1.1441 +
1.1442 +/**
1.1443 +Opens a handle to an LDD factory object by name.
1.1444 +
1.1445 +@param aName The name of the LDD factory object to be opened.
1.1446 +@param aType An enumeration whose enumerators define the ownership of this
1.1447 + LDD factory object handle.
1.1448 +
1.1449 +@return KErrNone, if successful; otherwise one of the other system wide error codes.
1.1450 +*/
1.1451 +EXPORT_C TInt RDevice::Open(const TDesC &aName,TOwnerType aType)
1.1452 + {
1.1453 + return OpenByName(aName,aType,ELogicalDevice);
1.1454 + }
1.1455 +
1.1456 +EXPORT_C TInt RBusLogicalChannel::DoCreate(const TDesC& aLogicalDevice, const TVersion& aVer, TInt aUnit, const TDesC* aPhysicalDevice, const TDesC8* anInfo, TInt aType)
1.1457 +//
1.1458 +// Call the kernel to create a channel on a device.
1.1459 +//
1.1460 + {
1.1461 + TInt r = User::ValidateName(aLogicalDevice);
1.1462 + if(KErrNone!=r)
1.1463 + return r;
1.1464 + TBuf8<KMaxKernelName> name8;
1.1465 + name8.Copy(aLogicalDevice);
1.1466 +
1.1467 + TBuf8<KMaxKernelName> physicalDeviceName;
1.1468 + TChannelCreateInfo8 info;
1.1469 + info.iVersion=aVer;
1.1470 + info.iUnit=aUnit;
1.1471 + if(aPhysicalDevice)
1.1472 + {
1.1473 + physicalDeviceName.Copy(*aPhysicalDevice);
1.1474 + info.iPhysicalDevice = &physicalDeviceName;
1.1475 + }
1.1476 + else
1.1477 + info.iPhysicalDevice = NULL;
1.1478 + info.iInfo=anInfo;
1.1479 +
1.1480 + return SetReturnedHandle(Exec::ChannelCreate(name8, info, aType),*this);
1.1481 + }
1.1482 +
1.1483 +
1.1484 +
1.1485 +
1.1486 +/**
1.1487 +Opens a handle to a logical channel using a handle number sent by a client
1.1488 +to a server.
1.1489 +
1.1490 +This function is called by the server.
1.1491 +
1.1492 +@param aMessage The message pointer.
1.1493 +@param aParam An index specifying which of the four message arguments
1.1494 + contains the handle number.
1.1495 +@param aType An enumeration whose enumerators define the ownership of this
1.1496 + logical channel handle. If not explicitly specified,
1.1497 + EOwnerProcess is taken as default.
1.1498 +
1.1499 +@return KErrNone, if successful;
1.1500 + KErrArgument, if the value of aParam is outside the range 0-3;
1.1501 + KErrBadHandle, if not a valid handle;
1.1502 + otherwise one of the other system-wide error codes.
1.1503 +*/
1.1504 +EXPORT_C TInt RBusLogicalChannel::Open(RMessagePtr2 aMessage,TInt aParam,TOwnerType aType)
1.1505 + {
1.1506 + return SetReturnedHandle(Exec::MessageOpenObject(aMessage.Handle(),ELogicalChannel,aParam,aType));
1.1507 + }
1.1508 +
1.1509 +
1.1510 +
1.1511 +
1.1512 +/**
1.1513 +Opens a logical channel handle using a handle number passed as an
1.1514 +environment data item to the child process during the creation of
1.1515 +that child process.
1.1516 +
1.1517 +Note that this function can only be called successfully once.
1.1518 +
1.1519 +@param aArgumentIndex An index that identifies the slot in the process
1.1520 + environment data that contains the handle number. This is
1.1521 + a value relative to zero, i.e. 0 is the first item/slot.
1.1522 + This can range from 0 to 15.
1.1523 +
1.1524 +@param aOwnerType An enumeration whose enumerators define the ownership of
1.1525 + this logical channel handle. If not explicitly specified,
1.1526 + EOwnerProcess is taken as default.
1.1527 +
1.1528 +@return KErrNone, if successful;
1.1529 + KErrNotFound, if the slot indicated by aArgumentIndex is empty;
1.1530 + KErrArgument, if the slot does not contain a logical channel handle;
1.1531 + otherwise one of the other system-wide error codes.
1.1532 +*/
1.1533 +EXPORT_C TInt RBusLogicalChannel::Open(TInt aArgumentIndex, TOwnerType aOwnerType)
1.1534 + {
1.1535 + return SetReturnedHandle(Exec::ProcessGetHandleParameter(aArgumentIndex, ELogicalChannel, aOwnerType));
1.1536 + }
1.1537 +
1.1538 +
1.1539 +
1.1540 +
1.1541 +EXPORT_C TInt RHandleBase::Duplicate(const RThread &aSrc,TOwnerType aType)
1.1542 +/**
1.1543 +Creates a valid handle to the kernel object for which the specified thread
1.1544 +already has a handle.
1.1545 +
1.1546 +The function assumes that this handle has been copy constructed from an existing
1.1547 +handle (or the handle-number has been explicitly copied through calls to Handle()
1.1548 +and SetHandle()).
1.1549 +
1.1550 +By default, any thread in the process can use this handle to access the kernel
1.1551 +side object that the handle represents. However, specifying EOwnerThread as
1.1552 +the second parameter to this function, means that only the creating thread
1.1553 +can use this handle to access the kernel side object; any other thread in
1.1554 +this process that wants to access the kernel side object must, again, duplicate
1.1555 +this handle.
1.1556 +
1.1557 +@param aSrc A reference to the thread containing the handle which is to be
1.1558 + duplicated for this thread.
1.1559 +@param aType An enumeration whose enumerators define the ownership of this
1.1560 + handle. If not explicitly specified, EOwnerProcess is taken
1.1561 + as default.
1.1562 +
1.1563 +@return KErrNone, if successful; otherwise, one of the other system wide error
1.1564 + codes.
1.1565 +*/
1.1566 + {
1.1567 + return Exec::HandleDuplicate(aSrc.Handle(), aType, iHandle);
1.1568 + }
1.1569 +
1.1570 +
1.1571 +
1.1572 +
1.1573 +EXPORT_C TInt RHandleBase::Open(const TFindHandleBase& aFindHandle, TOwnerType aType)
1.1574 +/**
1.1575 +Opens a handle to a kernel side object found using a find-handle object.
1.1576 +
1.1577 +@param aFindHandle A find-handle object; an object that is used in searching
1.1578 + for kernel side objects.
1.1579 +@param aType An enumeration whose enumerators define the ownership of
1.1580 + this handle. If not explicitly specified, EOwnerProcess
1.1581 + is taken as default, and ownership is vested in the
1.1582 + current process. Ownership can be vested in the current
1.1583 + thread by passing the EOwnerThread enumerator.
1.1584 +@return KErrNone, if successful; otherwise one of the other system wide
1.1585 + error codes.
1.1586 +*/
1.1587 + {
1.1588 + return SetReturnedHandle(Exec::FindHandleOpen(aType, aFindHandle), *this);
1.1589 + }
1.1590 +
1.1591 +
1.1592 +
1.1593 +/**
1.1594 + Implementation for RXxxxx::Open/OpenGlocbal(const TDesC &aName,,TOwnerType aType) functions
1.1595 + @internalComponent
1.1596 +*/
1.1597 +TInt RHandleBase::OpenByName(const TDesC &aName,TOwnerType aOwnerType,TInt aObjectType)
1.1598 + {
1.1599 + TBuf8<KMaxFullName> name8;
1.1600 + name8.Copy(aName);
1.1601 + return SetReturnedHandle(Exec::OpenObject((TObjectType)aObjectType,name8,aOwnerType));
1.1602 + }
1.1603 +
1.1604 +TInt RHandleBase::SetReturnedHandle(TInt aHandleOrError,RHandleBase& aHandle)
1.1605 +//
1.1606 +// Set the handle value or return error
1.1607 +//
1.1608 + {
1.1609 + return aHandle.SetReturnedHandle(aHandleOrError);
1.1610 + }
1.1611 +
1.1612 +
1.1613 +
1.1614 +
1.1615 +EXPORT_C void RHandleBase::Close()
1.1616 +/**
1.1617 +Closes the handle.
1.1618 +
1.1619 +This has the effect of closing the associated kernel side object.
1.1620 +
1.1621 +As the associated object is a reference counting object, it is destroyed if
1.1622 +there are no other open references to it.
1.1623 +
1.1624 +@see CObject
1.1625 +*/
1.1626 + {
1.1627 +
1.1628 + __IF_DEBUG(Print(_L("RHandleBase::Close")));
1.1629 + TInt h=iHandle;
1.1630 + if (h!=KNullHandle)
1.1631 + {
1.1632 +//
1.1633 +// We take a copy of the handle and set it to zero before the close in case this
1.1634 +// object is actually a Chunk created in its own heap in which case the close
1.1635 +// will destroy the object as well.
1.1636 +//
1.1637 + iHandle=0;
1.1638 + if ((h&CObjectIx::ENoClose)==0 && Exec::HandleClose(h)>0)
1.1639 + DoExtendedClose();
1.1640 + }
1.1641 + }
1.1642 +
1.1643 +
1.1644 +
1.1645 +
1.1646 +void RHandleBase::DoExtendedClose()
1.1647 +//
1.1648 +// Call static data destructors following a library handle close
1.1649 +//
1.1650 + {
1.1651 + TRAPD(r,DoExtendedCloseL()); // catch attempts to leave from destructors
1.1652 + __ASSERT_ALWAYS(r==KErrNone, Panic(EDllStaticDestructorLeave));
1.1653 + }
1.1654 +
1.1655 +void RHandleBase::DoExtendedCloseL()
1.1656 +//
1.1657 +// Call static data destructors following a library handle close
1.1658 +//
1.1659 + {
1.1660 + TLinAddr ep[KMaxLibraryEntryPoints];
1.1661 + TInt r=KErrNone;
1.1662 + while (r!=KErrEof)
1.1663 + {
1.1664 + TInt numEps=KMaxLibraryEntryPoints;
1.1665 + r=E32Loader::LibraryDetach(numEps, ep);
1.1666 + if (r==KErrEof)
1.1667 + break;
1.1668 + TInt i;
1.1669 + for (i=numEps-1; i>=0; --i)
1.1670 + {
1.1671 + TLibraryEntry f=(TLibraryEntry)ep[i];
1.1672 + (*f)(KModuleEntryReasonProcessDetach);
1.1673 + }
1.1674 + r=E32Loader::LibraryDetached();
1.1675 + }
1.1676 + }
1.1677 +
1.1678 +
1.1679 +
1.1680 +
1.1681 +/**
1.1682 +Constructs an RMessage2 from an RMessagePtr2.
1.1683 +
1.1684 +@param aPtr A reference to an existing RMessagePtr2 object.
1.1685 +*/
1.1686 +EXPORT_C RMessage2::RMessage2(const RMessagePtr2& aPtr)
1.1687 + {
1.1688 + iHandle = aPtr.Handle();
1.1689 + Exec::MessageConstructFromPtr(iHandle, this);
1.1690 + iFlags = 0;
1.1691 + iSpare3 = 0;
1.1692 + }
1.1693 +
1.1694 +/** Sets this message to an authorised state. This is used only by
1.1695 +CPolicyServer. This flags use by the policy server implies two things:
1.1696 +1) That the message has passed any appropriate security checks. (ie. one of the
1.1697 +static policy check, CustomSecurityCheckL, or CustomFailureActionL,
1.1698 +returned ETrue.)
1.1699 +2) That any leaves that occur subsequent to this flag being set happen _only_
1.1700 +in the session's ServiceL. ie. Nothing can leave between this flag being set
1.1701 +and the session's ServiceL being called.
1.1702 +
1.1703 +This is labelled as a const functions as everybody handles const RMessage2&'s.
1.1704 +The constness is actually referring to the underlying RMessagePtr2 not the
1.1705 +tranisent RMessage2 class.
1.1706 +
1.1707 +@internalComponent
1.1708 +*/
1.1709 +void RMessage2::SetAuthorised() const
1.1710 + {
1.1711 + iFlags = ETrue;
1.1712 + }
1.1713 +
1.1714 +/** Sets the authorised flag to a state of not authorised. This is required as
1.1715 +there is a default constructor for RMessage2 and one cannot guarantee that
1.1716 +iFlags was initialised. This is called from CPolicyServer::RunL.
1.1717 +
1.1718 +This is labelled as a const functions as everybody handles const RMessage2&'s.
1.1719 +The constness is actually referring to the underlying RMessagePtr2 not the
1.1720 +tranisent RMessage2 class.
1.1721 +
1.1722 +@internalComponent
1.1723 +*/
1.1724 +void RMessage2::ClearAuthorised() const
1.1725 + {
1.1726 + iFlags = EFalse;
1.1727 + }
1.1728 +
1.1729 +/** Returns whether this message has been authorised by CPolicyServer. See
1.1730 +RMessage2::SetAuthorised for implications of this state.
1.1731 +@internalComponent
1.1732 +*/
1.1733 +TBool RMessage2::Authorised() const
1.1734 + {
1.1735 + return iFlags;
1.1736 + }
1.1737 +
1.1738 +
1.1739 +
1.1740 +
1.1741 +/**
1.1742 +Frees this message.
1.1743 +
1.1744 +@param aReason The completion code.
1.1745 +*/
1.1746 +EXPORT_C void RMessagePtr2::Complete(TInt aReason) const
1.1747 +//
1.1748 +// Free this message. If it's a disconnect, need to switch to kernel context as we'll be
1.1749 +// freeing the DSession
1.1750 +//
1.1751 + {
1.1752 + TInt h=iHandle;
1.1753 + const_cast<TInt&>(iHandle)=0;
1.1754 + if (h)
1.1755 + Exec::MessageComplete(h,aReason);
1.1756 + else
1.1757 + ::Panic(ETMesCompletion);
1.1758 + }
1.1759 +
1.1760 +
1.1761 +
1.1762 +
1.1763 +/**
1.1764 +Duplicates the specified handle in the client thread, and returns this
1.1765 +handle as a message completion code
1.1766 +
1.1767 +@param aHandle The handle to be duplicated.
1.1768 +*/
1.1769 +EXPORT_C void RMessagePtr2::Complete(RHandleBase aHandle) const
1.1770 + {
1.1771 + TInt h=iHandle;
1.1772 + const_cast<TInt&>(iHandle)=0;
1.1773 + if (h)
1.1774 + Exec::MessageCompleteWithHandle(h,aHandle.Handle());
1.1775 + else
1.1776 + ::Panic(ETMesCompletion);
1.1777 + }
1.1778 +
1.1779 +
1.1780 +
1.1781 +
1.1782 +/**
1.1783 +Gets the length of a descriptor argument in the client's process.
1.1784 +
1.1785 +@param aParam The index value identifying the argument.
1.1786 + This is a value in the range 0 to (KMaxMessageArguments-1)
1.1787 + inclusive.
1.1788 +
1.1789 +@return The length of the descriptor, if successful.
1.1790 + KErrArgument, if aParam has a value outside the valid range.
1.1791 + KErrBadDescriptor, if the message argument is not a descriptor type.
1.1792 +*/
1.1793 +EXPORT_C TInt RMessagePtr2::GetDesLength(TInt aParam) const
1.1794 + {
1.1795 + return Exec::MessageGetDesLength(iHandle,aParam);
1.1796 + }
1.1797 +
1.1798 +
1.1799 +
1.1800 +
1.1801 +/**
1.1802 +Gets the length of a descriptor argument in the client's process,
1.1803 +leaving on failure.
1.1804 +
1.1805 +@param aParam The index value identifying the argument.
1.1806 + This is a value in the range 0 to (KMaxMessageArguments-1)
1.1807 + inclusive.
1.1808 +
1.1809 +@return The length of the descriptor.
1.1810 +
1.1811 +@leave KErrArgument if aParam has a value outside the valid range.
1.1812 +@leave KErrBadDescriptor, if the message argument is not a descriptor type.
1.1813 +*/
1.1814 +EXPORT_C TInt RMessagePtr2::GetDesLengthL(TInt aParam) const
1.1815 + {
1.1816 + return User::LeaveIfError(GetDesLength(aParam));
1.1817 + }
1.1818 +
1.1819 +
1.1820 +
1.1821 +
1.1822 +/**
1.1823 +Gets the maximum length of a descriptor argument in the client's process.
1.1824 +
1.1825 +@param aParam The index value identifying the argument.
1.1826 + This is a value in the range 0 to (KMaxMessageArguments-1)
1.1827 + inclusive.
1.1828 +
1.1829 +@return The maximum length of the descriptor, if successful.
1.1830 + KErrArgument, if aParam has a value outside the valid range.
1.1831 + KErrBadDescriptor, if the message argument is not a descriptor type.
1.1832 +*/
1.1833 +EXPORT_C TInt RMessagePtr2::GetDesMaxLength(TInt aParam) const
1.1834 + {
1.1835 + return Exec::MessageGetDesMaxLength(iHandle,aParam);
1.1836 + }
1.1837 +
1.1838 +
1.1839 +
1.1840 +
1.1841 +/**
1.1842 +Gets the maximum length of a descriptor argument in the client's process,
1.1843 +leaving on failure.
1.1844 +
1.1845 +@param aParam The index value identifying the argument.
1.1846 + This is a value in the range 0 to (KMaxMessageArguments-1)
1.1847 + inclusive.
1.1848 +
1.1849 +@return The length of the descriptor.
1.1850 +
1.1851 +@leave KErrArgument if aParam has a value outside the valid range.
1.1852 +@leave KErrBadDescriptor, if the message argument is not a descriptor type.
1.1853 +*/
1.1854 +EXPORT_C TInt RMessagePtr2::GetDesMaxLengthL(TInt aParam) const
1.1855 + {
1.1856 + return User::LeaveIfError(GetDesMaxLength(aParam));
1.1857 + }
1.1858 +
1.1859 +
1.1860 +
1.1861 +
1.1862 +/**
1.1863 +Reads data from the specified offset within the 8-bit descriptor
1.1864 +argument, into the specified target descriptor, and leaving on failure.
1.1865 +
1.1866 +@param aParam The index value identifying the argument.
1.1867 + This is a value in the range 0 to (KMaxMessageArguments-1)
1.1868 + inclusive.
1.1869 +@param aDes The target descriptor into which the client data is
1.1870 + to be written.
1.1871 +@param aOffset The offset from the start of the client's descriptor data.
1.1872 + If not explicitly specified, the offset defaults to zero.
1.1873 +
1.1874 +@leave KErrArgument if aParam has a value outside the valid range, or
1.1875 + if aOffset is negative.
1.1876 +@leave KErrBadDescriptor, if the message argument is not an 8-bit descriptor.
1.1877 +*/
1.1878 +EXPORT_C void RMessagePtr2::ReadL(TInt aParam,TDes8& aDes,TInt aOffset) const
1.1879 + {
1.1880 + TInt error = Read(aParam,aDes,aOffset);
1.1881 + User::LeaveIfError(error);
1.1882 + }
1.1883 +
1.1884 +
1.1885 +
1.1886 +
1.1887 +/**
1.1888 +Reads data from the specified offset within the 16-bit descriptor
1.1889 +argument, into the specified target descriptor, and leaving on failure.
1.1890 +
1.1891 +@param aParam The index value identifying the argument.
1.1892 + This is a value in the range 0 to (KMaxMessageArguments-1)
1.1893 + inclusive.
1.1894 +@param aDes The target descriptor into which the client data is
1.1895 + to be written.
1.1896 +@param aOffset The offset from the start of the client's descriptor data.
1.1897 + If not explicitly specified, the offset defaults to zero.
1.1898 +
1.1899 +@leave KErrArgument if aParam has a value outside the valid range, or
1.1900 + if aOffset is negative.
1.1901 +@leave KErrBadDescriptor, if the message argument is not a 16-bit descriptor.
1.1902 +*/
1.1903 +EXPORT_C void RMessagePtr2::ReadL(TInt aParam,TDes16 &aDes,TInt aOffset) const
1.1904 + {
1.1905 + TInt error = Read(aParam,aDes,aOffset);
1.1906 + User::LeaveIfError(error);
1.1907 + }
1.1908 +
1.1909 +
1.1910 +
1.1911 +
1.1912 +/**
1.1913 +Writes data from the specified source descriptor to the specified offset within
1.1914 +the 8-bit descriptor argument, and leaving on failure.
1.1915 +
1.1916 +@param aParam The index value identifying the argument.
1.1917 + This is a value in the range 0 to (KMaxMessageArguments-1)
1.1918 + inclusive.
1.1919 +@param aDes The source descriptor containing the data to be written.
1.1920 +@param aOffset The offset from the start of the client's descriptor.
1.1921 + If not explicitly specified, the offset defaults to zero.
1.1922 +
1.1923 +@leave KErrArgument if aParam has a value outside the valid range, or
1.1924 + if aOffset is negative.
1.1925 +@leave KErrBadDescriptor, if the message argument is not an 8-bit descriptor.
1.1926 +*/
1.1927 +EXPORT_C void RMessagePtr2::WriteL(TInt aParam,const TDesC8& aDes,TInt aOffset) const
1.1928 + {
1.1929 + TInt error = Write(aParam,aDes,aOffset);
1.1930 + User::LeaveIfError(error);
1.1931 + }
1.1932 +
1.1933 +
1.1934 +
1.1935 +
1.1936 +/**
1.1937 +Writes data from the specified source descriptor to the specified offset within
1.1938 +the 16-bit descriptor argument, and leaving on failure.
1.1939 +
1.1940 +@param aParam The index value identifying the argument.
1.1941 + This is a value in the range 0 to (KMaxMessageArguments-1)
1.1942 + inclusive.
1.1943 +@param aDes The source descriptor containing the data to be written.
1.1944 +@param aOffset The offset from the start of the client's descriptor.
1.1945 + If not explicitly specified, the offset defaults to zero.
1.1946 +
1.1947 +@leave KErrArgument if aParam has a value outside the valid range, or
1.1948 + if aOffset is negative.
1.1949 +@leave KErrBadDescriptor, if the message argument is not a 16-bit descriptor.
1.1950 +*/
1.1951 +EXPORT_C void RMessagePtr2::WriteL(TInt aParam,const TDesC16& aDes,TInt aOffset) const
1.1952 + {
1.1953 + TInt error = Write(aParam,aDes,aOffset);
1.1954 + User::LeaveIfError(error);
1.1955 + }
1.1956 +
1.1957 +
1.1958 +
1.1959 +
1.1960 +/**
1.1961 +Reads data from the specified offset within the 8-bit descriptor
1.1962 +argument, into the specified target descriptor.
1.1963 +
1.1964 +@param aParam The index value identifying the argument.
1.1965 + This is a value in the range 0 to (KMaxMessageArguments-1)
1.1966 + inclusive.
1.1967 +@param aDes The target descriptor into which the client data is
1.1968 + to be written.
1.1969 +@param aOffset The offset from the start of the client's descriptor data.
1.1970 + If not explicitly specified, the offset defaults to zero.
1.1971 +
1.1972 +@return KErrNone, if successful;
1.1973 + KErrArgument if aParam has a value outside the valid range, or
1.1974 + if aOffset is negative.
1.1975 + KErrBadDescriptor, if the message argument is not an 8-bit descriptor.
1.1976 +*/
1.1977 +EXPORT_C TInt RMessagePtr2::Read(TInt aParam,TDes8& aDes,TInt aOffset) const
1.1978 + {
1.1979 + SIpcCopyInfo info;
1.1980 + info.iFlags=KChunkShiftBy0|KIpcDirRead;
1.1981 + info.iLocalLen=aDes.MaxLength();
1.1982 + info.iLocalPtr=(TUint8*)aDes.Ptr();
1.1983 + TInt r=Exec::MessageIpcCopy(iHandle,aParam,info,aOffset);
1.1984 + if (r<0)
1.1985 + return r;
1.1986 + aDes.SetLength(r);
1.1987 + return KErrNone;
1.1988 + }
1.1989 +
1.1990 +
1.1991 +
1.1992 +
1.1993 +/**
1.1994 +Reads data from the specified offset within the 16-bit descriptor
1.1995 +argument, into the specified target descriptor.
1.1996 +
1.1997 +@param aParam The index value identifying the argument.
1.1998 + This is a value in the range 0 to (KMaxMessageArguments-1)
1.1999 + inclusive.
1.2000 +@param aDes The target descriptor into which the client data is
1.2001 + to be written.
1.2002 +@param aOffset The offset from the start of the client's descriptor data.
1.2003 + If not explicitly specified, the offset defaults to zero.
1.2004 +
1.2005 +@return KErrNone, if successful;
1.2006 + KErrArgument if aParam has a value outside the valid range, or
1.2007 + if aOffset is negative.
1.2008 + KErrBadDescriptor, if the message argument is not a 16-bit descriptor.
1.2009 +*/
1.2010 +EXPORT_C TInt RMessagePtr2::Read(TInt aParam,TDes16 &aDes,TInt aOffset) const
1.2011 + {
1.2012 + SIpcCopyInfo info;
1.2013 + info.iFlags=KChunkShiftBy1|KIpcDirRead;
1.2014 + info.iLocalLen=aDes.MaxLength();
1.2015 + info.iLocalPtr=(TUint8*)aDes.Ptr();
1.2016 + TInt r=Exec::MessageIpcCopy(iHandle,aParam,info,aOffset);
1.2017 + if (r<0)
1.2018 + return r;
1.2019 + aDes.SetLength(r);
1.2020 + return KErrNone;
1.2021 + }
1.2022 +
1.2023 +
1.2024 +
1.2025 +
1.2026 +/**
1.2027 +Writes data from the specified source descriptor to the specified offset within
1.2028 +the 8-bit descriptor argument.
1.2029 +
1.2030 +@param aParam The index value identifying the argument.
1.2031 + This is a value in the range 0 to (KMaxMessageArguments-1)
1.2032 + inclusive.
1.2033 +@param aDes The source descriptor containing the data to be written.
1.2034 +@param aOffset The offset from the start of the client's descriptor.
1.2035 + If not explicitly specified, the offset defaults to zero.
1.2036 +
1.2037 +@return KErrNone, if successful;
1.2038 + KErrArgument if aParam has a value outside the valid range, or
1.2039 + if aOffset is negative.
1.2040 + KErrBadDescriptor, if the message argument is not an 8-bit descriptor;
1.2041 + KErrOverflow, if the target descriptor is too small
1.2042 + to containt the data.
1.2043 +*/
1.2044 +EXPORT_C TInt RMessagePtr2::Write(TInt aParam,const TDesC8& aDes,TInt aOffset) const
1.2045 + {
1.2046 + SIpcCopyInfo info;
1.2047 + info.iFlags=KChunkShiftBy0|KIpcDirWrite;
1.2048 + info.iLocalLen=aDes.Length();
1.2049 + info.iLocalPtr=(TUint8*)aDes.Ptr();
1.2050 + return Exec::MessageIpcCopy(iHandle,aParam,info,aOffset);
1.2051 + }
1.2052 +
1.2053 +
1.2054 +
1.2055 +
1.2056 +/**
1.2057 +Writes data from the specified source descriptor to the specified offset within
1.2058 +the 16-bit descriptor argument.
1.2059 +
1.2060 +@param aParam The index value identifying the argument.
1.2061 + This is a value in the range 0 to (KMaxMessageArguments-1)
1.2062 + inclusive.
1.2063 +@param aDes The source descriptor containing the data to be written.
1.2064 +@param aOffset The offset from the start of the client's descriptor.
1.2065 + If not explicitly specified, the offset defaults to zero.
1.2066 +
1.2067 +@return KErrNone, if successful;
1.2068 + KErrArgument if aParam has a value outside the valid range, or
1.2069 + if aOffset is negative.
1.2070 + KErrBadDescriptor, if the message argument is not an 16-bit descriptor;
1.2071 + KErrOverflow, if the target descriptor is too small
1.2072 + to containt the data.
1.2073 +*/
1.2074 +EXPORT_C TInt RMessagePtr2::Write(TInt aParam,const TDesC16& aDes,TInt aOffset) const
1.2075 + {
1.2076 + SIpcCopyInfo info;
1.2077 + info.iFlags=KChunkShiftBy1|KIpcDirWrite;
1.2078 + info.iLocalLen=aDes.Length();
1.2079 + info.iLocalPtr=(TUint8*)aDes.Ptr();
1.2080 + return Exec::MessageIpcCopy(iHandle,aParam,info,aOffset);
1.2081 + }
1.2082 +
1.2083 +
1.2084 +
1.2085 +
1.2086 +/**
1.2087 +Panics the client.
1.2088 +
1.2089 +The length of the category name should be no greater than 16; any name with
1.2090 +a length greater than 16 is truncated to 16.
1.2091 +
1.2092 +Note that this method also completes the message. A subsequent call to Complete(TInt aReason) would cause a server panic.
1.2093 +
1.2094 +@param aCategory The panic category.
1.2095 +@param aReason The panic code.
1.2096 +*/
1.2097 +EXPORT_C void RMessagePtr2::Panic(const TDesC& aCategory,TInt aReason) const
1.2098 + {
1.2099 + TBuf8<KMaxExitCategoryName> cat;
1.2100 + TInt length=aCategory.Length();
1.2101 + if(length>KMaxExitCategoryName)
1.2102 + {
1.2103 + TPtr catPtr((TUint16*)aCategory.Ptr(),KMaxExitCategoryName,KMaxExitCategoryName);
1.2104 + cat.Copy(catPtr);
1.2105 + }
1.2106 + else
1.2107 + {
1.2108 + cat.Copy(aCategory);
1.2109 + }
1.2110 + Exec::MessageKill(iHandle,EExitPanic,aReason,&cat);
1.2111 + Complete(KErrNone);
1.2112 + }
1.2113 +
1.2114 +
1.2115 +
1.2116 +
1.2117 +/**
1.2118 +Kills the client.
1.2119 +
1.2120 +Note that this method also completes the message. A subsequent call to Complete(TInt aReason) would cause a server panic.
1.2121 +
1.2122 +@param aReason The reason code associated with killing the client.
1.2123 +*/
1.2124 +EXPORT_C void RMessagePtr2::Kill(TInt aReason) const
1.2125 + {
1.2126 + Exec::MessageKill(iHandle,EExitKill,aReason,NULL);
1.2127 + Complete(KErrNone);
1.2128 + }
1.2129 +
1.2130 +
1.2131 +
1.2132 +
1.2133 +/**
1.2134 +Terminates the client.
1.2135 +
1.2136 +Note that this method also completes the message. A subsequent call to Complete(TInt aReason) would cause a server panic.
1.2137 +
1.2138 +@param aReason The reason code associated with terminating the client.
1.2139 +*/
1.2140 +EXPORT_C void RMessagePtr2::Terminate(TInt aReason) const
1.2141 + {
1.2142 + Exec::MessageKill(iHandle,EExitTerminate,aReason,NULL);
1.2143 + Complete(KErrNone);
1.2144 + }
1.2145 +
1.2146 +
1.2147 +
1.2148 +
1.2149 +/**
1.2150 +Sets the priority of the client's process.
1.2151 +
1.2152 +@param aPriority The priority value.
1.2153 +
1.2154 +@return KErrNone, if successful, otherwise one of the other system-wide error codes.
1.2155 +*/
1.2156 +EXPORT_C TInt RMessagePtr2::SetProcessPriority(TProcessPriority aPriority) const
1.2157 + {
1.2158 + return Exec::MessageSetProcessPriority(iHandle,aPriority);
1.2159 + }
1.2160 +
1.2161 +
1.2162 +
1.2163 +/**
1.2164 +Opens a handle on the client thread.
1.2165 +
1.2166 +@param aClient On successful return, the handle to the client thread.
1.2167 +@param aOwnerType An enumeration whose enumerators define the ownership of
1.2168 + the handle. If not explicitly specified,
1.2169 + EOwnerProcess is taken as default.
1.2170 +
1.2171 +@return KErrNone.
1.2172 +*/
1.2173 +EXPORT_C TInt RMessagePtr2::Client(RThread& aClient, TOwnerType aOwnerType) const
1.2174 + {
1.2175 + return aClient.SetReturnedHandle(Exec::MessageClient(iHandle,aOwnerType));
1.2176 + }
1.2177 +
1.2178 +EXPORT_C TUint RMessagePtr2::ClientProcessFlags() const
1.2179 + {
1.2180 + return Exec::MessageClientProcessFlags(iHandle);
1.2181 + }
1.2182 +
1.2183 +EXPORT_C TBool RMessagePtr2::ClientIsRealtime() const
1.2184 + {
1.2185 + return (Exec::MessageClientProcessFlags(iHandle) & KThreadFlagRealtime) != 0;
1.2186 + }
1.2187 +
1.2188 +
1.2189 +
1.2190 +/**
1.2191 +Returns the pointer to the clients TRequestStatus associated with the message.
1.2192 +
1.2193 +The return value is intended to be used as a unique identifier (for example,
1.2194 +to uniquely identify an asynchronous message when cancelling the request).
1.2195 +The memory must never be accessed directly or completed.
1.2196 +
1.2197 +@return The clients TRequestStatus (returns NULL if the request is not asynchronous)
1.2198 +*/
1.2199 +EXPORT_C const TRequestStatus* RMessagePtr2::ClientStatus() const
1.2200 + {
1.2201 + return Exec::MessageClientStatus(iHandle);
1.2202 + }
1.2203 +
1.2204 +
1.2205 +
1.2206 +EXPORT_C TInt RServer2::CreateGlobal(const TDesC& aName, TInt aMode, TInt aRole, TInt aOpts)
1.2207 +//
1.2208 +// Create a new server.
1.2209 +//
1.2210 + {
1.2211 + TInt r = User::ValidateName(aName);
1.2212 + if (r != KErrNone)
1.2213 + return r;
1.2214 + TBuf8<KMaxKernelName> name8;
1.2215 + name8.Copy(aName);
1.2216 + r = Exec::ServerCreateWithOptions(&name8, aMode, aRole, aOpts);
1.2217 + return SetReturnedHandle(r, *this);
1.2218 + }
1.2219 +
1.2220 +EXPORT_C TInt RServer2::CreateGlobal(const TDesC& aName, TInt aMode)
1.2221 + {
1.2222 + return CreateGlobal(aName, aMode, EServerRole_Default, 0);
1.2223 + }
1.2224 +
1.2225 +EXPORT_C TInt RServer2::CreateGlobal(const TDesC& aName)
1.2226 + {
1.2227 + return CreateGlobal(aName, EIpcSession_Sharable);
1.2228 + }
1.2229 +
1.2230 +TInt RSessionBase::DoConnect(const TVersion &aVersion,TRequestStatus* aStatus)
1.2231 + {
1.2232 + extern int TVersion_size_assert[sizeof(TVersion)==sizeof(TInt)?1:-1]; // Make sure TVersion is same size as int
1.2233 + (void)TVersion_size_assert;
1.2234 +
1.2235 + TIpcArgs p(*(TInt*)&aVersion);
1.2236 + TInt r;
1.2237 + if(aStatus==NULL)
1.2238 + r = SendSync(RMessage2::EConnect, &p);
1.2239 + else
1.2240 + r = SendAsync(RMessage2::EConnect, &p, aStatus);
1.2241 + if (r!=KErrNone)
1.2242 + Close();
1.2243 + return r;
1.2244 + }
1.2245 +
1.2246 +
1.2247 +
1.2248 +
1.2249 +/**
1.2250 +Creates a session with a server.
1.2251 +
1.2252 +It should be called as part of session initialisation in the derived class.
1.2253 +
1.2254 +@param aServer The name of the server with which a session is to
1.2255 + be established.
1.2256 +@param aVersion The lowest version of the server with which this client
1.2257 + is compatible.
1.2258 +@param aAsyncMessageSlots The number of message slots available to this session.
1.2259 + This determines the number of outstanding requests the client
1.2260 + may have with the server at any one time.
1.2261 + The maximum number of slots is 255.
1.2262 + If aAsyncMessageSlots==-1 then this indicates that the session should use
1.2263 + messages from the global free pool of messages.
1.2264 +@param aType The type of session to create. See TIpcSessionType.
1.2265 +@param aPolicy A pointer to a TSecurityPolicy object. If this pointer is not 0 (zero)
1.2266 + then the policy is applied to the process in which the server is running.
1.2267 + If that process doesn't pass this security policy check, then the session
1.2268 + creation will fail with the error KErrPermissionDenied.
1.2269 + This security check allows clients to verify that the server has the expected
1.2270 + Platform Security attributes.
1.2271 +
1.2272 + When a check fails the action taken is determined by the system wide Platform Security
1.2273 + configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted.
1.2274 + If PlatSecEnforcement is OFF, then this function will return KErrNone even though the
1.2275 + check failed.
1.2276 +
1.2277 +@param aStatus A pointer to TRequestStatus object which will be signalled when the session
1.2278 + has been created, or in the event of an error.
1.2279 + If aStatus==0 then session creation is done synchronously.
1.2280 +
1.2281 +@return KErrNone if successful;
1.2282 + KErrArgument, if an attempt is made to specify more
1.2283 + than 255 message slots;
1.2284 + otherwise one of the other system-wide error codes.
1.2285 +*/
1.2286 +EXPORT_C TInt RSessionBase::CreateSession(const TDesC& aServer,const TVersion& aVersion,TInt aAsyncMessageSlots,TIpcSessionType aType,const TSecurityPolicy* aPolicy, TRequestStatus* aStatus)
1.2287 + {
1.2288 + TInt r = User::ValidateName(aServer);
1.2289 + if(KErrNone!=r)
1.2290 + return r;
1.2291 + TBuf8<KMaxKernelName> name8;
1.2292 + name8.Copy(aServer);
1.2293 + r=SetReturnedHandle(Exec::SessionCreate(name8,aAsyncMessageSlots,aPolicy,aType));
1.2294 + if(r==KErrNone)
1.2295 + r=DoConnect(aVersion,aStatus);
1.2296 + return r;
1.2297 + }
1.2298 +
1.2299 +
1.2300 +
1.2301 +
1.2302 +/**
1.2303 +Creates a session with a server.
1.2304 +
1.2305 +It should be called as part of session initialisation in the derived class.
1.2306 +
1.2307 +@param aServer The name of the server with which a session is to
1.2308 + be established.
1.2309 +@param aVersion The lowest version of the server with which this client
1.2310 + is compatible.
1.2311 +@param aAsyncMessageSlots The number of message slots available to this session.
1.2312 + This determines the number of outstanding requests the client
1.2313 + may have with the server at any one time.
1.2314 + The maximum number of slots is 255.
1.2315 + If aAsyncMessageSlots==-1 then this indicates that the session should use
1.2316 + messages from the global free pool of messages.
1.2317 +
1.2318 +@return KErrNone if successful;
1.2319 + KErrArgument, if an attempt is made to specify more
1.2320 + than 255 message slots;
1.2321 + otherwise one of the other system-wide error codes.
1.2322 +*/
1.2323 +EXPORT_C TInt RSessionBase::CreateSession(const TDesC &aServer, const TVersion &aVersion, TInt aAsyncMessageSlots)
1.2324 + {
1.2325 + return RSessionBase::CreateSession(aServer,aVersion,aAsyncMessageSlots,EIpcSession_Unsharable,NULL,0);
1.2326 + }
1.2327 +
1.2328 +
1.2329 +
1.2330 +
1.2331 +/**
1.2332 +Creates a session with a server.
1.2333 +
1.2334 +It should be called as part of session initialisation in the derived class.
1.2335 +
1.2336 +@param aServer A handle to a server with which a session is to be established.
1.2337 +@param aVersion The lowest version of the server with which this client
1.2338 + is compatible.
1.2339 +@param aAsyncMessageSlots The number of message slots available to this session.
1.2340 + This determines the number of outstanding requests the client
1.2341 + may have with the server at any one time.
1.2342 + The maximum number of slots is 255.
1.2343 + If aAsyncMessageSlots==-1 then this indicates that the session should use
1.2344 + messages from the global free pool of messages.
1.2345 +@param aType The type of session to create. See TIpcSessionType.
1.2346 +@param aPolicy A pointer to a TSecurityPolicy object. If this pointer is not 0 (zero)
1.2347 + then the policy is applied to the process in which the server is running.
1.2348 + If that process doesn't pass this security policy check, then the session
1.2349 + creation will fail with the error KErrPermissionDenied.
1.2350 + This security check allows clients to verify that the server has the expected
1.2351 + Platform Security attributes.
1.2352 +
1.2353 + When a check fails the action taken is determined by the system wide Platform Security
1.2354 + configuration. If PlatSecDiagnostics is ON, then a diagnostic message is emitted.
1.2355 + If PlatSecEnforcement is OFF, then this function will return KErrNone even though the
1.2356 + check failed.
1.2357 +
1.2358 +@param aStatus A pointer to TRequestStatus object which will be signalled when the session
1.2359 + has been created, or in the event of an error.
1.2360 + If aStatus==0 then session creation is done synchronously.
1.2361 +
1.2362 +@return KErrNone if successful;
1.2363 + KErrArgument, if an attempt is made to specify more
1.2364 + than 255 message slots;
1.2365 + otherwise one of the other system-wide error codes.
1.2366 +*/
1.2367 +EXPORT_C TInt RSessionBase::CreateSession(RServer2 aServer,const TVersion& aVersion,TInt aAsyncMessageSlots,TIpcSessionType aType,const TSecurityPolicy* aPolicy, TRequestStatus* aStatus)
1.2368 + {
1.2369 + TInt r;
1.2370 + r=SetReturnedHandle(Exec::SessionCreateFromHandle(aServer.Handle(),aAsyncMessageSlots,aPolicy,aType));
1.2371 + if(r==KErrNone)
1.2372 + r=DoConnect(aVersion,aStatus);
1.2373 + return r;
1.2374 + }
1.2375 +
1.2376 +
1.2377 +
1.2378 +
1.2379 +/**
1.2380 +Creates a session with a server.
1.2381 +
1.2382 +It should be called as part of session initialisation in the derived class.
1.2383 +
1.2384 +@param aServer A handle to a server with which a session is to be established.
1.2385 +@param aVersion The lowest version of the server with which this client
1.2386 + is compatible.
1.2387 +@param aAsyncMessageSlots The number of message slots available to this session.
1.2388 + This determines the number of outstanding requests the client
1.2389 + may have with the server at any one time.
1.2390 + The maximum number of slots is 255.
1.2391 + If aAsyncMessageSlots==-1 then this indicates that the session should use
1.2392 + messages from the global free pool of messages.
1.2393 +
1.2394 +@return KErrNone if successful;
1.2395 + KErrArgument, if an attempt is made to specify more
1.2396 + than 255 message slots;
1.2397 + otherwise one of the other system-wide error codes.
1.2398 +*/
1.2399 +EXPORT_C TInt RSessionBase::CreateSession(RServer2 aServer, const TVersion &aVersion, TInt aAsyncMessageSlots)
1.2400 + {
1.2401 + return RSessionBase::CreateSession(aServer,aVersion,aAsyncMessageSlots,EIpcSession_Unsharable,NULL,0);
1.2402 + }
1.2403 +
1.2404 +
1.2405 +
1.2406 +
1.2407 +/**
1.2408 +Opens a handle to a session using a handle number sent by a client
1.2409 +to a server.
1.2410 +
1.2411 +This function is called by the server.
1.2412 +
1.2413 +@param aMessage The message pointer.
1.2414 +@param aParam An index specifying which of the four message arguments
1.2415 + contains the handle number.
1.2416 +@param aType An enumeration whose enumerators define the ownership of this
1.2417 + session handle. If not explicitly specified, EOwnerProcess
1.2418 + is taken as default.
1.2419 +
1.2420 +@return KErrNone, if successful;
1.2421 + KErrArgument, if the value of aParam is outside the range 0-3;
1.2422 + KErrBadHandle, if not a valid handle;
1.2423 + otherwise one of the other system-wide error codes.
1.2424 +*/
1.2425 +EXPORT_C TInt RSessionBase::Open(RMessagePtr2 aMessage,TInt aParam,TOwnerType aType)
1.2426 + {
1.2427 + return SetReturnedHandle(Exec::MessageOpenObject(aMessage.Handle(),ESession,aParam,aType));
1.2428 + }
1.2429 +
1.2430 +
1.2431 +
1.2432 +
1.2433 +/**
1.2434 +Opens a handle to a session using a handle number sent by a client
1.2435 +to a server, and validate that the session's server passes a given
1.2436 +security policy.
1.2437 +
1.2438 +This function is called by the server.
1.2439 +
1.2440 +@param aMessage The message pointer.
1.2441 +@param aParam An index specifying which of the four message arguments
1.2442 + contains the handle number.
1.2443 +@param aServerPolicy The policy to validate the session's server against.
1.2444 +@param aType An enumeration whose enumerators define the ownership of this
1.2445 + session handle. If not explicitly specified, EOwnerProcess
1.2446 + is taken as default.
1.2447 +
1.2448 +@return KErrNone, if successful;
1.2449 + KErrArgument, if the value of aParam is outside the range 0-3;
1.2450 + KErrBadHandle, if not a valid handle;
1.2451 + KErrServerTerminating, if the session is no longer connected to a server;
1.2452 + KErrPermissionDenied, if the session's server does not pass the given security policy;
1.2453 + otherwise one of the other system-wide error codes.
1.2454 +*/
1.2455 +EXPORT_C TInt RSessionBase::Open(RMessagePtr2 aMessage,TInt aParam,const TSecurityPolicy& aServerPolicy,TOwnerType aType)
1.2456 + {
1.2457 + return SetReturnedHandle(Exec::MessageOpenObject(aMessage.Handle(),ESession,aParam,aType),aServerPolicy);
1.2458 + }
1.2459 +
1.2460 +
1.2461 +
1.2462 +/**
1.2463 +Sets the handle-number of this session handle to the specified value after
1.2464 +validating that the session's server passes a given security policy.
1.2465 +
1.2466 +The function can take a (zero or positive) handle-number,
1.2467 +or a (negative) error number.
1.2468 +
1.2469 +If aHandleOrError represents a handle-number, then the handle-number of this handle
1.2470 +is set to that value, as long as the session's server passes the security policy.
1.2471 +If aHandleOrError represents an error number, then the handle-number of this handle is set to zero
1.2472 +and the negative value is returned.
1.2473 +
1.2474 +@param aHandleOrError A handle-number, if zero or positive; an error value, if negative.
1.2475 +@param aServerPolicy The policy to validate the session's server against.
1.2476 +
1.2477 +@return KErrNone, if aHandle is a handle-number; KErrPermissionDenied, if the session's server
1.2478 + does not pass the security policy; the value of aHandleOrError, otherwise.
1.2479 +*/
1.2480 +EXPORT_C TInt RSessionBase::SetReturnedHandle(TInt aHandleOrError,const TSecurityPolicy& aServerPolicy)
1.2481 + {
1.2482 + if(aHandleOrError<0)
1.2483 + return aHandleOrError;
1.2484 +
1.2485 + TInt r = aServerPolicy.CheckPolicy((RSessionBase&)aHandleOrError);
1.2486 + if (r!=KErrNone)
1.2487 + {
1.2488 + ((RHandleBase&)aHandleOrError).Close();
1.2489 + return r;
1.2490 + }
1.2491 +
1.2492 + iHandle=aHandleOrError;
1.2493 + return KErrNone;
1.2494 + }
1.2495 +
1.2496 +
1.2497 +
1.2498 +
1.2499 +/**
1.2500 +Opens a handle to a session using a handle number passed as an
1.2501 +environment data item to the child process during the creation of
1.2502 +that child process.
1.2503 +
1.2504 +Note that this function can only be called successfully once.
1.2505 +
1.2506 +@param aArgumentIndex An index that identifies the slot in the process
1.2507 + environment data that contains the handle number. This is
1.2508 + a value relative to zero, i.e. 0 is the first item/slot.
1.2509 + This can range from 0 to 15.
1.2510 +
1.2511 +@param aOwnerType An enumeration whose enumerators define the ownership of
1.2512 + this session handle. If not explicitly specified,
1.2513 + EOwnerProcess is taken as default.
1.2514 +
1.2515 +@return KErrNone, if successful;
1.2516 + KErrNotFound, if the slot indicated by aArgumentIndex is empty;
1.2517 + KErrArgument, if the slot does not contain a session handle;
1.2518 + otherwise one of the other system-wide error codes.
1.2519 +*/
1.2520 +EXPORT_C TInt RSessionBase::Open(TInt aArgumentIndex, TOwnerType aOwnerType)
1.2521 + {
1.2522 + return SetReturnedHandle(Exec::ProcessGetHandleParameter(aArgumentIndex, ESession, aOwnerType));
1.2523 + }
1.2524 +
1.2525 +
1.2526 +/**
1.2527 +Opens a handle to a session using a handle number passed as an
1.2528 +environment data item to the child process during the creation of
1.2529 +that child process, after validating that the session's server passes
1.2530 +the given security policy.
1.2531 +
1.2532 +Note that this function can only be called successfully once.
1.2533 +
1.2534 +@param aArgumentIndex An index that identifies the slot in the process
1.2535 + environment data that contains the handle number. This is
1.2536 + a value relative to zero, i.e. 0 is the first item/slot.
1.2537 + This can range from 0 to 15.
1.2538 +@param aServerPolicy The policy to validate the session's server against.
1.2539 +@param aOwnerType An enumeration whose enumerators define the ownership of
1.2540 + this session handle. If not explicitly specified,
1.2541 + EOwnerProcess is taken as default.
1.2542 +
1.2543 +@return KErrNone, if successful;
1.2544 + KErrNotFound, if the slot indicated by aArgumentIndex is empty;
1.2545 + KErrArgument, if the slot does not contain a session handle;
1.2546 + KErrServerTerminating, if the session is no longer connected to a server;
1.2547 + KErrPermissionDenied, if the session's server does not pass the given security policy;
1.2548 + otherwise one of the other system-wide error codes.
1.2549 +*/
1.2550 +EXPORT_C TInt RSessionBase::Open(TInt aArgumentIndex, const TSecurityPolicy& aServerPolicy, TOwnerType aOwnerType)
1.2551 + {
1.2552 + return SetReturnedHandle(Exec::ProcessGetHandleParameter(aArgumentIndex, ESession, aOwnerType), aServerPolicy);
1.2553 + }
1.2554 +
1.2555 +
1.2556 +EXPORT_C TInt RSessionBase::DoShare(TInt aMode)
1.2557 +//
1.2558 +// Make the session accessible to all threads in this process
1.2559 +//
1.2560 + {
1.2561 + return Exec::SessionShare(iHandle, (aMode&KCreateProtectedObject) ? EIpcSession_GlobalSharable : EIpcSession_Sharable);
1.2562 + }
1.2563 +
1.2564 +
1.2565 +
1.2566 +
1.2567 +TInt RSessionBase::SendSync(TInt aFunction,const TIpcArgs* aArgs) const
1.2568 +//
1.2569 +// Send a synchronous message.
1.2570 +//
1.2571 + {
1.2572 + TRequestStatus s=KRequestPending;
1.2573 + TInt r=Exec::SessionSendSync(iHandle,aFunction,(TAny*)aArgs,&s);
1.2574 + if (r==KErrNone)
1.2575 + {
1.2576 + User::WaitForRequest(s);
1.2577 + r=s.Int();
1.2578 + }
1.2579 + return r;
1.2580 + }
1.2581 +
1.2582 +TInt RSessionBase::SendAsync(TInt aFunction,const TIpcArgs* aArgs,TRequestStatus *aStatus) const
1.2583 +//
1.2584 +// Send an asynchronous message.
1.2585 +//
1.2586 + {
1.2587 + if (aStatus)
1.2588 + *aStatus=KRequestPending;
1.2589 + return Exec::SessionSend(iHandle,aFunction,(TAny*)aArgs,aStatus);
1.2590 + }
1.2591 +
1.2592 +
1.2593 +
1.2594 +
1.2595 +EXPORT_C TInt RMutex::CreateLocal(TOwnerType aType)
1.2596 +/**
1.2597 +Creates a mutex and opens this handle to the mutex.
1.2598 +
1.2599 +The kernel side object representing the mutex is unnamed. This means that
1.2600 +it is not possible to search for the mutex, which makes it local to the current
1.2601 +process.
1.2602 +
1.2603 +By default, any thread in the process can use this instance of RMutex to access
1.2604 +the mutex. However, specifying EOwnerThread as the parameter to this function,
1.2605 +means that only the creating thread can use this instance of RMutex to access
1.2606 +the mutex; any other thread in this process that wants to access the mutex
1.2607 +must duplicate this handle.
1.2608 +
1.2609 +@param aType An enumeration whose enumerators define the ownership of this
1.2610 + mutex handle. If not explicitly specified, EOwnerProcess is taken
1.2611 + as default.
1.2612 +
1.2613 +@return KErrNone if successful, otherwise one of the system wide error codes.
1.2614 +
1.2615 +@see RHandleBase::Duplicate()
1.2616 +*/
1.2617 + {
1.2618 + return SetReturnedHandle(Exec::MutexCreate(NULL,aType),*this);
1.2619 + }
1.2620 +
1.2621 +
1.2622 +
1.2623 +
1.2624 +EXPORT_C TInt RMutex::CreateGlobal(const TDesC &aName,TOwnerType aType)
1.2625 +/**
1.2626 +Creates a global mutex and opens this handle to the mutex.
1.2627 +
1.2628 +The kernel side object representing the mutex is given the name contained
1.2629 +in the specified descriptor, which makes it global. This means that any thread
1.2630 +in any process can search for the mutex, using TFindMutex, and open a handle
1.2631 +to it. If the specified name is empty the kernel side object representing the
1.2632 +mutex is unnamed and so cannot be opened by name. It can however be passed
1.2633 +to another process as a process parameter or via IPC.
1.2634 +
1.2635 +By default, any thread in the process can use this instance of RMutex to access
1.2636 +the mutex. However, specifying EOwnerThread as the second parameter to this
1.2637 +function, means that only the creating thread can use this instance of RMutex
1.2638 +to access the mutex; any other thread in this process that wants to access
1.2639 +the mutex must either duplicate this handle or use OpenGlobal().
1.2640 +
1.2641 +@param aName The name to be assigned to this global mutex.
1.2642 +@param aType An enumeration whose enumerators define the ownership of this
1.2643 + mutex handle. If not explicitly specified, EOwnerProcess is
1.2644 + taken as default.
1.2645 +
1.2646 +@return KErrNone if successful, otherwise one of the other system wide error
1.2647 + codes.
1.2648 +
1.2649 +@see OpenGlobal
1.2650 +@see RHandleBase::Duplicate()
1.2651 +@see TFindMutex
1.2652 +*/
1.2653 + {
1.2654 + TInt r = User::ValidateName(aName);
1.2655 + if(KErrNone!=r)
1.2656 + return r;
1.2657 + TBuf8<KMaxKernelName> name8;
1.2658 + name8.Copy(aName);
1.2659 + return SetReturnedHandle(Exec::MutexCreate(&name8,aType),*this);
1.2660 + }
1.2661 +
1.2662 +
1.2663 +
1.2664 +
1.2665 +EXPORT_C TInt RMutex::OpenGlobal(const TDesC &aName,TOwnerType aType)
1.2666 +/**
1.2667 +Opens a handle to a global mutex.
1.2668 +
1.2669 +Global mutexes are identified by name.
1.2670 +
1.2671 +By default, any thread in the process can use this instance of RMutex to access
1.2672 +the mutex. However, specifying EOwnerThread as the second parameter to this
1.2673 +function, means that only the opening thread can use this instance of RMutex
1.2674 +to access the mutex; any other thread in this process that wants to access
1.2675 +the mutex must either duplicate the handle or use OpenGlobal() again.
1.2676 +
1.2677 +@param aName The name of the global mutex which is to be opened.
1.2678 +@param aType An enumeration whose enumerators define the ownership of this
1.2679 + mutex handle. If not explicitly specified, EOwnerProcess
1.2680 + is taken as default.
1.2681 +
1.2682 +@return KErrNone if successful, otherwise another of the system wide error
1.2683 + codes.
1.2684 +@see RHandleBase::Duplicate()
1.2685 +*/
1.2686 + {
1.2687 + return OpenByName(aName,aType,EMutex);
1.2688 + }
1.2689 +
1.2690 +
1.2691 +
1.2692 +
1.2693 +EXPORT_C TInt RMutex::Open(RMessagePtr2 aMessage,TInt aParam,TOwnerType aType)
1.2694 +/**
1.2695 +Opens a handle to a mutex using a handle number sent by a client
1.2696 +to a server.
1.2697 +
1.2698 +This function is called by the server.
1.2699 +
1.2700 +@param aMessage The message pointer.
1.2701 +@param aParam An index specifying which of the four message arguments
1.2702 + contains the handle number.
1.2703 +@param aType An enumeration whose enumerators define the ownership of this
1.2704 + mutex handle. If not explicitly specified, EOwnerProcess is
1.2705 + taken as default.
1.2706 +
1.2707 +@return KErrNone, if successful;
1.2708 + KErrArgument, if the value of aParam is outside the range 0-3;
1.2709 + KErrBadHandle, if not a valid handle;
1.2710 + otherwise one of the other system-wide error codes.
1.2711 +*/
1.2712 + {
1.2713 + return SetReturnedHandle(Exec::MessageOpenObject(aMessage.Handle(),EMutex,aParam,aType));
1.2714 + }
1.2715 +
1.2716 +
1.2717 +
1.2718 +
1.2719 +EXPORT_C TInt RMutex::Open(TInt aArgumentIndex, TOwnerType aOwnerType)
1.2720 +/**
1.2721 +Opens a handle to a mutex using a handle number passed as an
1.2722 +environment data item to the child process during the creation of
1.2723 +that child process.
1.2724 +
1.2725 +Note that this function can only be called successfully once.
1.2726 +
1.2727 +@param aArgumentIndex An index that identifies the slot in the process
1.2728 + environment data that contains the handle number. This is
1.2729 + a value relative to zero, i.e. 0 is the first item/slot.
1.2730 + This can range from 0 to 15.
1.2731 +
1.2732 +@param aOwnerType An enumeration whose enumerators define the ownership of
1.2733 + this mutex handle. If not explicitly specified,
1.2734 + EOwnerProcess is taken as default.
1.2735 +
1.2736 +@return KErrNone, if successful;
1.2737 + KErrNotFound, if the slot indicated by aArgumentIndex is empty;
1.2738 + KErrArgument, if the slot does not contain a mutex handle;
1.2739 + otherwise one of the other system-wide error codes.
1.2740 +
1.2741 +@see RProcess::SetParameter()
1.2742 +*/
1.2743 + {
1.2744 + return SetReturnedHandle(Exec::ProcessGetHandleParameter(aArgumentIndex, EMutex, aOwnerType));
1.2745 + }
1.2746 +
1.2747 +
1.2748 +
1.2749 +EXPORT_C TInt RCondVar::CreateLocal(TOwnerType aType)
1.2750 +/**
1.2751 +Creates a condition variable and opens this handle to it.
1.2752 +
1.2753 +The kernel side object representing the condition variable is unnamed and so
1.2754 +the condition variable cannot be found by name and hence it is local to the
1.2755 +current process.
1.2756 +
1.2757 +By default, any thread in the process can use this instance of RCondVar to access
1.2758 +the condition variable. However, specifying EOwnerThread as the parameter to this
1.2759 +function means that only the creating thread can use this instance of RCondVar
1.2760 +to access the condition variable; any other thread in this process that wants to
1.2761 +access the condition variable must duplicate this handle.
1.2762 +
1.2763 +@param aType An enumeration whose enumerators define the ownership of this
1.2764 + condition variable handle. If not explicitly specified, EOwnerProcess
1.2765 + is taken as default.
1.2766 +
1.2767 +@return KErrNone if successful, otherwise one of the system wide error codes.
1.2768 +
1.2769 +@see RHandleBase::Duplicate()
1.2770 +*/
1.2771 + {
1.2772 + return SetReturnedHandle(Exec::CondVarCreate(NULL, aType), *this);
1.2773 + }
1.2774 +
1.2775 +
1.2776 +
1.2777 +
1.2778 +EXPORT_C TInt RCondVar::CreateGlobal(const TDesC& aName, TOwnerType aType)
1.2779 +/**
1.2780 +Creates a global condition variable and opens this handle to it.
1.2781 +
1.2782 +If the specified name is a non-empty string the kernel side object representing
1.2783 +the condition variable is given the specified name and is therefore global. It
1.2784 +may subsequently be opened by name using the RCondVar::OpenGlobal function.
1.2785 +If the specified name is empty the kernel side object representing the condition
1.2786 +variable is unnamed and so cannot be opened by name. It can however be passed
1.2787 +to another process as a process parameter or via IPC.
1.2788 +
1.2789 +If the specified name is non-empty it must consist entirely of printable ASCII
1.2790 +characters (codes 0x20 to 0x7e inclusive) and may not contain : * or ?.
1.2791 +
1.2792 +By default, any thread in the process can use this instance of RCondVar to access
1.2793 +the condition variable. However, specifying EOwnerThread as the parameter to this
1.2794 +function means that only the creating thread can use this instance of RCondVar
1.2795 +to access the condition variable; any other thread in this process that wants to
1.2796 +access the condition variable must duplicate this handle.
1.2797 +
1.2798 +@param aName The name to be assigned to this condition variable.
1.2799 +@param aType An enumeration whose enumerators define the ownership of this
1.2800 + condition variable handle. If not explicitly specified, EOwnerProcess
1.2801 + is taken as default.
1.2802 +
1.2803 +@return KErrNone if successful, otherwise one of the other system wide error
1.2804 + codes.
1.2805 +
1.2806 +@see RCondVar::OpenGlobal()
1.2807 +@see RHandleBase::Duplicate()
1.2808 +@see RProcess::SetParameter(TInt, RHandleBase)
1.2809 +@see TIpcArgs::Set(TInt, RHandleBase)
1.2810 +@see RMessagePtr2::Complete(RHandleBase)
1.2811 +*/
1.2812 + {
1.2813 + TInt r = User::ValidateName(aName);
1.2814 + if (KErrNone!=r)
1.2815 + return r;
1.2816 + TBuf8<KMaxKernelName> name8;
1.2817 + name8.Copy(aName);
1.2818 + return SetReturnedHandle(Exec::CondVarCreate(&name8, aType), *this);
1.2819 + }
1.2820 +
1.2821 +
1.2822 +
1.2823 +
1.2824 +EXPORT_C TInt RCondVar::OpenGlobal(const TDesC& aName, TOwnerType aType)
1.2825 +/**
1.2826 +Opens a handle to a global condition variable.
1.2827 +
1.2828 +Global condition variables are identified by name.
1.2829 +
1.2830 +By default, any thread in the process can use this instance of RCondVar to access
1.2831 +the condition variable. However, specifying EOwnerThread as the parameter to this
1.2832 +function means that only the creating thread can use this instance of RCondVar
1.2833 +to access the condition variable; any other thread in this process that wants to
1.2834 +access the condition variable must either duplicate this handle or use OpenGlobal
1.2835 +again.
1.2836 +
1.2837 +@param aName The name of the global condition variable which is to be opened.
1.2838 +@param aType An enumeration whose enumerators define the ownership of this
1.2839 + condition variable handle. If not explicitly specified, EOwnerProcess
1.2840 + is taken as default.
1.2841 +
1.2842 +@return KErrNone if successful, otherwise another of the system wide error
1.2843 + codes.
1.2844 +
1.2845 +@see RHandleBase::Duplicate()
1.2846 +*/
1.2847 + {
1.2848 + return OpenByName(aName, aType, ECondVar);
1.2849 + }
1.2850 +
1.2851 +
1.2852 +
1.2853 +
1.2854 +EXPORT_C TInt RCondVar::Open(RMessagePtr2 aMessage, TInt aParam, TOwnerType aType)
1.2855 +/**
1.2856 +Opens a handle to a condition variable using a handle number sent by a client
1.2857 +to a server.
1.2858 +
1.2859 +This function is called by the server.
1.2860 +
1.2861 +@param aMessage The message pointer.
1.2862 +@param aParam An index specifying which of the four message arguments
1.2863 + contains the handle number.
1.2864 +@param aType An enumeration whose enumerators define the ownership of this
1.2865 + condition variable handle. If not explicitly specified, EOwnerProcess
1.2866 + is taken as default.
1.2867 +
1.2868 +@return KErrNone, if successful;
1.2869 + KErrArgument, if the value of aParam is outside the range 0-3;
1.2870 + KErrBadHandle, if not a valid handle;
1.2871 + otherwise one of the other system-wide error codes.
1.2872 +*/
1.2873 + {
1.2874 + return SetReturnedHandle(Exec::MessageOpenObject(aMessage.Handle(), ECondVar, aParam, aType));
1.2875 + }
1.2876 +
1.2877 +
1.2878 +
1.2879 +
1.2880 +EXPORT_C TInt RCondVar::Open(TInt aArgumentIndex, TOwnerType aType)
1.2881 +/**
1.2882 +Opens a handle to a condition variable using a handle number passed as an
1.2883 +environment data item to the child process during the creation of
1.2884 +that child process.
1.2885 +
1.2886 +Note that this function can only be called successfully once.
1.2887 +
1.2888 +@param aArgumentIndex An index that identifies the slot in the process
1.2889 + environment data that contains the handle number. This is
1.2890 + a value relative to zero, i.e. 0 is the first item/slot.
1.2891 + This can range from 0 to 15.
1.2892 +
1.2893 +@param aType An enumeration whose enumerators define the ownership of
1.2894 + this condition variable handle. If not explicitly specified,
1.2895 + EOwnerProcess is taken as default.
1.2896 +
1.2897 +@return KErrNone, if successful;
1.2898 + KErrNotFound, if the slot indicated by aArgumentIndex is empty;
1.2899 + KErrArgument, if the slot does not contain a condition variable handle;
1.2900 + otherwise one of the other system-wide error codes.
1.2901 +
1.2902 +@see RProcess::SetParameter()
1.2903 +*/
1.2904 + {
1.2905 + return SetReturnedHandle(Exec::ProcessGetHandleParameter(aArgumentIndex, ECondVar, aType));
1.2906 + }
1.2907 +
1.2908 +
1.2909 +
1.2910 +
1.2911 +EXPORT_C TInt RSemaphore::CreateLocal(TInt aCount,TOwnerType aType)
1.2912 +/**
1.2913 +Creates a semaphore, setting its initial count, and opens this handle to the
1.2914 +semaphore.
1.2915 +
1.2916 +The kernel side object representing the semaphore is unnamed. This means that
1.2917 +it is not possible to search for the semaphore, which makes it local to the
1.2918 +current process.
1.2919 +
1.2920 +By default, any thread in the process can use this instance of RSemaphore
1.2921 +to access the semaphore. However, specifying EOwnerThread as the second parameter
1.2922 +to this function, means that only the creating thread can use this instance
1.2923 +of RSemaphore to access the semaphore; any other thread in this process that
1.2924 +wants to access the semaphore must duplicate this handle.
1.2925 +
1.2926 +@param aCount The initial value of the semaphore count.
1.2927 +@param aType An enumeration whose enumerators define the ownership of this
1.2928 + semaphore handle. If not explicitly specified, EOwnerProcess is
1.2929 + taken as default.
1.2930 +
1.2931 +@return KErrNone if successful, otherwise another of the system wide error
1.2932 + codes.
1.2933 +
1.2934 +@panic USER 105 if aCount is negative.
1.2935 +
1.2936 +@see RHandleBase::Duplicate()
1.2937 +*/
1.2938 + {
1.2939 +
1.2940 + __ASSERT_ALWAYS(aCount>=0,Panic(ESemCreateCountNegative));
1.2941 + return SetReturnedHandle(Exec::SemaphoreCreate(NULL,aCount,aType),*this);
1.2942 + }
1.2943 +
1.2944 +
1.2945 +
1.2946 +
1.2947 +EXPORT_C TInt RSemaphore::CreateGlobal(const TDesC &aName,TInt aCount,TOwnerType aType)
1.2948 +/**
1.2949 +Creates a global semaphore, setting its initial count, and opens this handle
1.2950 +to the semaphore.
1.2951 +
1.2952 +The kernel side object representing the semaphore is given the name contained
1.2953 +in the specified descriptor, which makes it global. This means that any thread
1.2954 +in any process can search for the semaphore, using TFindSemaphore, and open
1.2955 +a handle to it. If the specified name is empty the kernel side object
1.2956 +representing the semaphore is unnamed and so cannot be opened by name. It can
1.2957 +however be passed to another process as a process parameter or via IPC.
1.2958 +
1.2959 +By default, any thread in the process can use this instance of RSemaphore
1.2960 +to access the semaphore. However, specifying EOwnerThread as the third
1.2961 +parameter to this function, means that only the creating thread can use
1.2962 +this instance of RSemaphore to access the semaphore; any other thread in
1.2963 +this process that wants to access the semaphore must either duplicate this
1.2964 +handle or use OpenGlobal().
1.2965 +
1.2966 +@param aName A reference to the descriptor containing the name to be assigned
1.2967 + to this global semaphore.
1.2968 +@param aCount The initial value of the semaphore count.
1.2969 +@param aType An enumeration whose enumerators define the ownership of this
1.2970 + semaphore handle. If not explicitly specified, EOwnerProcess is
1.2971 + taken as default.
1.2972 +
1.2973 +@return KErrNone if successful otherwise another of the system wide error
1.2974 + codes.
1.2975 +
1.2976 +@panic USER 105 if aCount is negative.
1.2977 +
1.2978 +@see RSemaphore::OpenGlobal()
1.2979 +@see RHandleBase::Duplicate()
1.2980 +@see TFindSemaphore
1.2981 +*/
1.2982 + {
1.2983 +
1.2984 + __ASSERT_ALWAYS(aCount>=0,Panic(ESemCreateCountNegative));
1.2985 + TInt r = User::ValidateName(aName);
1.2986 + if(KErrNone!=r)
1.2987 + return r;
1.2988 + TBuf8<KMaxKernelName> name8;
1.2989 + name8.Copy(aName);
1.2990 + return SetReturnedHandle(Exec::SemaphoreCreate(&name8,aCount,aType),*this);
1.2991 + }
1.2992 +
1.2993 +
1.2994 +
1.2995 +
1.2996 +EXPORT_C TInt RSemaphore::OpenGlobal(const TDesC &aName,TOwnerType aType)
1.2997 +/**
1.2998 +Opens a handle to a global semaphore.
1.2999 +
1.3000 +Global semaphores are identified by name.
1.3001 +
1.3002 +By default, any thread in the process can use this instance of RSemaphore
1.3003 +to access the semaphore. However, specifying EOwnerThread as the second parameter
1.3004 +to this function, means that only the opening thread can use this instance
1.3005 +of RSemaphore to access the semaphore; any other thread in this process that
1.3006 +wants to access the semaphore must either duplicate the handle or use OpenGlobal()
1.3007 +again.
1.3008 +
1.3009 +@param aName A reference to the descriptor containing the name of the global
1.3010 + semaphore to be opened.
1.3011 +@param aType An enumeration whose enumerators define the ownership of this
1.3012 + semaphore handle. If not explicitly specified, EOwnerProcess is
1.3013 + taken as default.
1.3014 +
1.3015 +@return KErrNone if successful otherwise another of the system wide error
1.3016 + codes.
1.3017 +
1.3018 +@see RHandleBase::Duplicate()
1.3019 +*/
1.3020 + {
1.3021 + return OpenByName(aName,aType,ESemaphore);
1.3022 + }
1.3023 +
1.3024 +
1.3025 +
1.3026 +
1.3027 +EXPORT_C TInt RSemaphore::Open(RMessagePtr2 aMessage,TInt aParam,TOwnerType aType)
1.3028 +/**
1.3029 +Opens a handle to a semaphore using a handle number sent by a client
1.3030 +to a server.
1.3031 +
1.3032 +This function is called by the server.
1.3033 +
1.3034 +@param aMessage The message pointer.
1.3035 +@param aParam An index specifying which of the four message arguments
1.3036 + contains the handle number.
1.3037 +@param aType An enumeration whose enumerators define the ownership of this
1.3038 + semaphore handle. If not explicitly specified, EOwnerProcess is
1.3039 + taken as default.
1.3040 +
1.3041 +@return KErrNone, if successful;
1.3042 + KErrArgument, if the value of aParam is outside the range 0-3;
1.3043 + KErrBadHandle, if not a valid handle;
1.3044 + otherwise one of the other system-wide error codes.
1.3045 +*/
1.3046 + {
1.3047 + return SetReturnedHandle(Exec::MessageOpenObject(aMessage.Handle(),ESemaphore,aParam,aType));
1.3048 + }
1.3049 +
1.3050 +
1.3051 +
1.3052 +
1.3053 +EXPORT_C TInt RSemaphore::Open(TInt aArgumentIndex, TOwnerType aOwnerType)
1.3054 +/**
1.3055 +Opens a handle to a semaphore using a handle number passed as an
1.3056 +environment data item to the child process during the creation of
1.3057 +that child process.
1.3058 +
1.3059 +Note that this function can only be called successfully once.
1.3060 +
1.3061 +@param aArgumentIndex An index that identifies the slot in the process
1.3062 + environment data that contains the handle number. This is
1.3063 + a value relative to zero, i.e. 0 is the first item/slot.
1.3064 + This can range from 0 to 15.
1.3065 +
1.3066 +@param aOwnerType An enumeration whose enumerators define the ownership of
1.3067 + this semaphore handle. If not explicitly specified,
1.3068 + EOwnerProcess is taken as default.
1.3069 +
1.3070 +@return KErrNone, if successful;
1.3071 + KErrNotFound, if the slot indicated by aArgumentIndex is empty;
1.3072 + KErrArgument, if the slot does not contain a Semaphore handle;
1.3073 + otherwise one of the other system-wide error codes.
1.3074 +
1.3075 +@see RProcess::SetParameter()
1.3076 +*/
1.3077 + {
1.3078 + return SetReturnedHandle(Exec::ProcessGetHandleParameter(aArgumentIndex, ESemaphore, aOwnerType));
1.3079 + }
1.3080 +
1.3081 +
1.3082 +
1.3083 +
1.3084 +EXPORT_C TInt RCriticalSection::CreateLocal(TOwnerType aType)
1.3085 +/**
1.3086 +Creates a critical section and opens this handle to the critical section.
1.3087 +
1.3088 +The kernel side object representing the critical section is unnamed. This
1.3089 +means that it is not possible to search for the critical section, which makes
1.3090 +it local to the current process.
1.3091 +
1.3092 +By default, any thread in the process can use this instance of RCriticalSection
1.3093 +to access the critical section. However, specifying EOwnerThread as the parameter
1.3094 +to this function, means that only the creating thread can use this instance
1.3095 +of RCriticalSection to access the critical section; any other thread in this
1.3096 +process that wants to access the critical section must duplicate this handle.
1.3097 +
1.3098 +@param aType An enumeration whose enumerators define the ownership of this
1.3099 + critical section handle. If not explicitly specified,
1.3100 + EOwnerProcess is taken as default.
1.3101 +
1.3102 +@return KErrNone if successful otherwise another of the system wide error codes.
1.3103 +
1.3104 +@see RHandleBase::Duplicate()
1.3105 +*/
1.3106 + {
1.3107 +
1.3108 + iBlocked=1;
1.3109 + return(RSemaphore::CreateLocal(0,aType));
1.3110 + }
1.3111 +
1.3112 +
1.3113 +
1.3114 +/**
1.3115 +Creates a local fast semaphore, and opens this handle to the
1.3116 +semaphore.
1.3117 +
1.3118 +@param aType An enumeration whose enumerators define the ownership of this
1.3119 + semaphore handle. If not explicitly specified, EOwnerProcess is
1.3120 + taken as default.
1.3121 +
1.3122 +@return KErrNone if successful, otherwise one of the system wide error
1.3123 + codes.
1.3124 +
1.3125 +@see RSemaphore::CreateLocal()
1.3126 +*/
1.3127 +EXPORT_C TInt RFastLock::CreateLocal(TOwnerType aType)
1.3128 + {
1.3129 +
1.3130 + iCount=0;
1.3131 + return RSemaphore::CreateLocal(0,aType);
1.3132 + }
1.3133 +
1.3134 +
1.3135 +
1.3136 +
1.3137 +EXPORT_C TInt RTimer::CreateLocal()
1.3138 +//
1.3139 +// Create a local timer.
1.3140 +//
1.3141 +/**
1.3142 +Creates a thread-relative timer.
1.3143 +
1.3144 +@return KErrNone if successful, otherwise another of the
1.3145 + system-wide error codes.
1.3146 +*/
1.3147 + {
1.3148 + return SetReturnedHandle(Exec::TimerCreate(),*this);
1.3149 + }
1.3150 +
1.3151 +
1.3152 +
1.3153 +
1.3154 +EXPORT_C TInt RProcess::Open(const TDesC &aName,TOwnerType aType)
1.3155 +/**
1.3156 +Opens a handle to a specifically named process.
1.3157 +
1.3158 +By default, ownership of this process handle is vested in the current process,
1.3159 +but can be vested in the current thread by passing EOwnerThread as the second
1.3160 +parameter to this function.
1.3161 +
1.3162 +@param aName A reference to the descriptor containing the name of the process
1.3163 + to be opened.
1.3164 +@param aType An enumeration whose enumerators define the ownership of this
1.3165 + thread handle. If not explicitly specified, EOwnerProcess is
1.3166 + taken as default.
1.3167 +
1.3168 +@return KErrNone, if successful, otherwise one of the other system-wide error
1.3169 + codes.
1.3170 +*/
1.3171 + {
1.3172 + return OpenByName(aName,aType,EProcess);
1.3173 + }
1.3174 +
1.3175 +
1.3176 +
1.3177 +
1.3178 +EXPORT_C TInt RProcess::Open(TProcessId aId,TOwnerType aType)
1.3179 +/**
1.3180 +Opens a handle to the process whose process Id matches
1.3181 +the specified process ID.
1.3182 +
1.3183 +By default, ownership of this process handle is vested in the current process,
1.3184 +but can be vested in the current thread by passing EOwnerThread as the second
1.3185 +parameter to this function.
1.3186 +
1.3187 +@param aId The process Id used to find the process.
1.3188 +@param aType An enumeration whose enumerators define the ownership of this
1.3189 + process handle. If not explicitly specified, EOwnerProcess is
1.3190 + taken as default.
1.3191 +
1.3192 +@return KErrNone, if successful, otherwise one of the other system-wide error
1.3193 + codes.
1.3194 +*/
1.3195 + {
1.3196 +
1.3197 + TUint id=*(TUint*)&aId;
1.3198 + return SetReturnedHandle(Exec::ProcessOpenById(id,aType),*this);
1.3199 + }
1.3200 +
1.3201 +
1.3202 +
1.3203 +
1.3204 +EXPORT_C TInt User::RenameProcess(const TDesC &aName)
1.3205 +/**
1.3206 +Assigns a new name to the current process, replacing any existing name.
1.3207 +
1.3208 +When a process is created, its default name is the name portion of the filename
1.3209 +from which the executable is loaded.
1.3210 +
1.3211 +The new name must be a valid name and it must also be such that the process's
1.3212 +new fullname remains unique amongst processes.
1.3213 +
1.3214 +@param aName A reference to the descriptor containing the new name of the
1.3215 + process.
1.3216 +
1.3217 +@return KErrNone, if successful, or if the new and old names are identical;
1.3218 + KErrBadName, if aName is an invalid;
1.3219 + otherwise one of the other system-wide error codes.
1.3220 +*/
1.3221 + {
1.3222 + TBuf8<KMaxKernelName> name8;
1.3223 + name8.Copy(aName);
1.3224 + return Exec::ProcessRename(KCurrentProcessHandle,name8);
1.3225 + }
1.3226 +
1.3227 +
1.3228 +
1.3229 +
1.3230 +/**
1.3231 +Ends this process, and all of its threads, specifying a reason code.
1.3232 +
1.3233 +This function is intended to be used if a process is exiting under normal
1.3234 +conditions.
1.3235 +
1.3236 +If the process is system permanent, the entire system is rebooted.
1.3237 +
1.3238 +@param aReason The reason to be associated with the ending of this process.
1.3239 +
1.3240 +@capability PowerMgmt except when one of the following situations is true:
1.3241 + 1. the process calling this function is the same as the
1.3242 + process to be terminated.
1.3243 + 2. the process calling this function created the process
1.3244 + to be terminated, but has not yet resumed that process.
1.3245 +
1.3246 +@see User::SetProcessCritical()
1.3247 +@see User::ProcessCritical()
1.3248 +*/
1.3249 +EXPORT_C void RProcess::Kill(TInt aReason)
1.3250 + {
1.3251 + Exec::ProcessKill(iHandle,EExitKill,aReason,NULL);
1.3252 + }
1.3253 +
1.3254 +
1.3255 +/**
1.3256 +Ends this process, and all of its threads, specifying a reason code.
1.3257 +
1.3258 +This function is intended to be used if a process is exiting under abnormal
1.3259 +conditions, for example if an error condition has been detected.
1.3260 +
1.3261 +If the process is system critical or system permanent, the entire system is
1.3262 +rebooted.
1.3263 +
1.3264 +@param aReason The reason to be associated with the ending of this process.
1.3265 +
1.3266 +@capability PowerMgmt except when one of the following situations is true:
1.3267 + 1. the process calling this function is the same as the
1.3268 + process to be terminated.
1.3269 + 2. the process calling this function created the process
1.3270 + to be terminated, but has not yet resumed that process.
1.3271 +
1.3272 +@see User::SetProcessCritical()
1.3273 +@see User::ProcessCritical()
1.3274 +*/
1.3275 +EXPORT_C void RProcess::Terminate(TInt aReason)
1.3276 + {
1.3277 + Exec::ProcessKill(iHandle,EExitTerminate,aReason,NULL);
1.3278 + }
1.3279 +
1.3280 +
1.3281 +
1.3282 +/**
1.3283 +Panics the process and all of its owned threads, specifying the panic category
1.3284 +name and reason code.
1.3285 +
1.3286 +The length of the category name should be no greater than 16; any name with
1.3287 +a length greater than 16 is truncated to 16.
1.3288 +
1.3289 +If the process is system critical or system permanent, the entire system is
1.3290 +rebooted.
1.3291 +
1.3292 +@param aCategory A reference to the descriptor containing the text which
1.3293 + defines the category name for this panic.
1.3294 +@param aReason The panic number.
1.3295 +
1.3296 +@capability PowerMgmt except when one of the following situations is true:
1.3297 + 1. the process calling this function is the same as the
1.3298 + process to be terminated.
1.3299 + 2. the process calling this function created the process
1.3300 + to be terminated, but has not yet resumed that process.
1.3301 +
1.3302 +@see User::SetProcessCritical()
1.3303 +@see User::ProcessCritical()
1.3304 +*/
1.3305 +EXPORT_C void RProcess::Panic(const TDesC &aCategory,TInt aReason)
1.3306 + {
1.3307 + TBuf8<KMaxExitCategoryName> name8;
1.3308 + TInt length=aCategory.Length();
1.3309 + if(length>KMaxExitCategoryName)
1.3310 + {
1.3311 + TPtr catPtr((TUint16*)aCategory.Ptr(),KMaxExitCategoryName,KMaxExitCategoryName);
1.3312 + name8.Copy(catPtr);
1.3313 + }
1.3314 + else
1.3315 + {
1.3316 + name8.Copy(aCategory);
1.3317 + }
1.3318 + Exec::ProcessKill(iHandle,EExitPanic,aReason,&name8);
1.3319 + }
1.3320 +
1.3321 +
1.3322 +
1.3323 +
1.3324 +EXPORT_C void RProcess::Logon(TRequestStatus &aStatus) const
1.3325 +/**
1.3326 +Requests notification when this process dies, normally or otherwise.
1.3327 +
1.3328 +A request for notification is an asynchronous request, and completes:
1.3329 +
1.3330 +- when the process terminates
1.3331 +- if the outstanding request is cancelled by a call to RProcess::LogonCancel().
1.3332 +
1.3333 +A request for notification requires memory to be allocated; if this is
1.3334 +unavailable, then the call to Logon() returns, and the asynchronous request
1.3335 +completes immediately.
1.3336 +
1.3337 +@param aStatus A reference to the request status object.
1.3338 + This contains the reason code describing the reason for
1.3339 + the termination of the process, i.e. the value returned by a call to RProcess::ExitReason().
1.3340 + Alternatively, this is set to:
1.3341 + KErrCancel, if an outstanding request is cancelled;
1.3342 + KErrNoMemory, if there is insufficient memory to deal with the request.
1.3343 +
1.3344 +@see RProcess::LogonCancel()
1.3345 +@see RProcess::ExitReason()
1.3346 +*/
1.3347 + {
1.3348 +
1.3349 + aStatus=KRequestPending;
1.3350 + Exec::ProcessLogon(iHandle,&aStatus,EFalse);
1.3351 + }
1.3352 +
1.3353 +
1.3354 +
1.3355 +
1.3356 +EXPORT_C TInt RProcess::LogonCancel(TRequestStatus &aStatus) const
1.3357 +/**
1.3358 +Cancels an outstanding request for notification of the death of this process.
1.3359 +
1.3360 +A request for notification must previously have been made, otherwise the function
1.3361 +returns KErrGeneral.
1.3362 +
1.3363 +The caller passes a reference to the same request status object as was passed
1.3364 +in the original call to Logon().
1.3365 +
1.3366 +@param aStatus A reference to the same request status object used in
1.3367 + the original call to Logon().
1.3368 +
1.3369 +@return KErrGeneral, if there is no outstanding request; KErrNone otherwise.
1.3370 +
1.3371 +@see RProcess::Logon()
1.3372 +*/
1.3373 + {
1.3374 + return Exec::ProcessLogonCancel(iHandle,&aStatus,EFalse);
1.3375 + }
1.3376 +
1.3377 +
1.3378 +
1.3379 +
1.3380 +/**
1.3381 +Creates a Rendezvous request with the process.
1.3382 +
1.3383 +The request is an asynchronous request, and completes:
1.3384 +
1.3385 +- when a call is made to RProcess::Rendezvous(TInt aReason).
1.3386 +- if the outstanding request is cancelled by a call to RProcess::RendezvousCancel()
1.3387 +- if the process exits
1.3388 +- if the process panics.
1.3389 +
1.3390 +Note that a request requires memory to be allocated; if this is unavailable,
1.3391 +then this call to Rendezvous() returns, and the asynchronous request
1.3392 +completes immediately.
1.3393 +
1.3394 +@param aStatus A reference to the request status object.
1.3395 + The Rendezvous completes normally when
1.3396 + RProcess::Rendezvous(TInt aReason) is called, and this
1.3397 + request status object will contain this reason code.
1.3398 + If the process exits or panics, then this is the process exit
1.3399 + reason value, i.e. the same value returned by RProcess::ExitReason().
1.3400 + Alternatively, this is set to:
1.3401 + KErrCancel, if an outstanding request is cancelled;
1.3402 + KErrNoMemory, if there is insufficient memory to deal with the request.
1.3403 +
1.3404 +@see RProcess::Rendezvous(TInt aReason)
1.3405 +@see RProcess::RendezvousCancel(TRequestStatus& aStatus)
1.3406 +*/
1.3407 +EXPORT_C void RProcess::Rendezvous(TRequestStatus& aStatus) const
1.3408 + {
1.3409 + aStatus=KRequestPending;
1.3410 + Exec::ProcessLogon(iHandle,&aStatus,ETrue);
1.3411 + }
1.3412 +
1.3413 +
1.3414 +
1.3415 +
1.3416 +/**
1.3417 +Cancels a previously requested Rendezvous with the process.
1.3418 +
1.3419 +The request completes with the value KErrCancel (if it was still outstanding).
1.3420 +
1.3421 +@param aStatus A reference to the same request status object used in
1.3422 + the original call to Rendezvous(TRequestStatus& aStatus).
1.3423 +
1.3424 +@return KErrGeneral, if there is no outstanding request, KErrNone otherwise.
1.3425 +
1.3426 +@see RProcess::Rendezvous(TRequestStatus &aStatus)
1.3427 +*/
1.3428 +EXPORT_C TInt RProcess::RendezvousCancel(TRequestStatus& aStatus) const
1.3429 + {
1.3430 + return Exec::ProcessLogonCancel(iHandle,&aStatus,ETrue);
1.3431 + }
1.3432 +
1.3433 +
1.3434 +
1.3435 +
1.3436 +/**
1.3437 +Completes all Rendezvous' with the current process.
1.3438 +
1.3439 +@param aReason The reason code used to complete all rendezvous requests
1.3440 +
1.3441 +@see RProcess::Rendezvous(TRequestStatus& aStatus)
1.3442 +*/
1.3443 +EXPORT_C void RProcess::Rendezvous(TInt aReason)
1.3444 + {
1.3445 + Exec::ProcessRendezvous(aReason);
1.3446 + }
1.3447 +
1.3448 +
1.3449 +/**
1.3450 +This can be used to determine whether the data for the process is demand paged
1.3451 +by default or not.
1.3452 +
1.3453 +@return ETrue if the default for the process's data is to be demand paged,
1.3454 + EFalse otherwise.
1.3455 +
1.3456 +@prototype
1.3457 +*/
1.3458 +EXPORT_C TBool RProcess::DefaultDataPaged() const
1.3459 + {
1.3460 + return Exec::ProcessDefaultDataPaged(iHandle);
1.3461 + }
1.3462 +
1.3463 +
1.3464 +//
1.3465 +// Class TThreadCreateInfo
1.3466 +//
1.3467 +
1.3468 +/**
1.3469 +Constructor where the basic properties of the thread to be created are specified.
1.3470 +
1.3471 +NOTE - TThreadCreateInfo::SetCreateHeap() or TThreadCreateInfo::SetUseHeap() must
1.3472 +be invoked on this TThreadCreateInfo to set the type of the thread to be created
1.3473 +before being passed as a paramter to RThread::Create().
1.3474 +
1.3475 +@param aName The name to be assigned to the thread.
1.3476 + KNullDesC, to create an anonymous thread.
1.3477 +@param aFunction A pointer to a function. Control passes to this function
1.3478 + when the thread is first resumed, i.e. when the thread
1.3479 + is initially scheduled to run.
1.3480 +@param aStackSize The size of the new thread's stack.
1.3481 +@param aPtr A pointer to data to be passed as a parameter to
1.3482 + the thread function when the thread is initially scheduled
1.3483 + to run. If the thread function does not need any data then
1.3484 + this pointer can be NULL.
1.3485 +*/
1.3486 +EXPORT_C TThreadCreateInfo::TThreadCreateInfo(const TDesC &aName, TThreadFunction aFunction,
1.3487 + TInt aStackSize, TAny* aPtr) :
1.3488 + iVersionNumber(EVersion0), iName(&aName), iFunction(aFunction),
1.3489 + iStackSize(aStackSize), iParameter(aPtr), iOwner(EOwnerProcess), iHeap(NULL),
1.3490 + iHeapMinSize(0), iHeapMaxSize(0), iAttributes(0)
1.3491 + {
1.3492 + };
1.3493 +
1.3494 +
1.3495 +/**
1.3496 +Sets the thread to be created to create its own heap.
1.3497 +
1.3498 +@param aHeapMinSize The minimum size for the new thread's heap.
1.3499 +@param aHeapMaxSize The maximum size for the new thread's heap.
1.3500 +*/
1.3501 +EXPORT_C void TThreadCreateInfo::SetCreateHeap(TInt aHeapMinSize, TInt aHeapMaxSize)
1.3502 + {
1.3503 + iHeapMinSize = aHeapMinSize;
1.3504 + iHeapMaxSize = aHeapMaxSize;
1.3505 + }
1.3506 +
1.3507 +
1.3508 +/**
1.3509 +Sets the thread to be created to use the heap whose handle is pointed to by
1.3510 +aAllocator. If this is NULL, then the thread uses the heap of the creating thread.
1.3511 +
1.3512 +@param aAllocator A pointer to the handle of the heap belonging to another thread
1.3513 + which this thread is to use.
1.3514 +*/
1.3515 +EXPORT_C void TThreadCreateInfo::SetUseHeap(const RAllocator *aAllocator)
1.3516 + {
1.3517 + iHeap = (aAllocator)? (RAllocator*)aAllocator : GetHeap();
1.3518 + }
1.3519 +
1.3520 +
1.3521 +/**
1.3522 +Sets the owner the thread to be created. Any previous calls
1.3523 +to this method will be overridden for this TThreadCreateInfo object.
1.3524 +
1.3525 +@param aOwner The owner of the thread to be created.
1.3526 +*/
1.3527 +EXPORT_C void TThreadCreateInfo::SetOwner(const TOwnerType aOwner)
1.3528 + {
1.3529 + iOwner = aOwner;
1.3530 + }
1.3531 +
1.3532 +
1.3533 +/**
1.3534 +Sets the data paging attributes of the thread to be created. Any previous calls
1.3535 +to this method will be overridden for this TThreadCreateInfo object.
1.3536 +
1.3537 +@param aPaging The paging attributes for the thread to be created.
1.3538 +*/
1.3539 +EXPORT_C void TThreadCreateInfo::SetPaging(const TThreadPagingAtt aPaging)
1.3540 + {
1.3541 + iAttributes &= ~EThreadCreateFlagPagingMask;
1.3542 + if (aPaging == EPaged)
1.3543 + iAttributes |= EThreadCreateFlagPaged;
1.3544 + if (aPaging == EUnpaged)
1.3545 + iAttributes |= EThreadCreateFlagUnpaged;
1.3546 + }
1.3547 +
1.3548 +
1.3549 +/**
1.3550 +Creates a thread belonging to the current process, and opens this handle
1.3551 +to that thread. The thread will have the properties as defined by the parameter
1.3552 +aCreateInfo.
1.3553 +
1.3554 +@param aCreateInfo A reference to a TThreadCreateInfo object specifying
1.3555 + the properties of thread to create.
1.3556 +
1.3557 +@return KErrNone if successful, otherwise one of the other system-wide error codes.
1.3558 + KErrAlreadyExists will be returned if there is another thread in this process with the
1.3559 + specified name.
1.3560 +
1.3561 +@panic USER 109 if the stack size specified for the thread is negative.
1.3562 +@panic USER 110 if the specified minimum heap size is less than KMinHeapSize.
1.3563 +@panic USER 111 if the specified maximum heap size is less than the specified minimum heap size.
1.3564 +*/
1.3565 +EXPORT_C TInt RThread::Create(const TThreadCreateInfo& aCreateInfo)
1.3566 + {
1.3567 + __ASSERT_ALWAYS(aCreateInfo.iStackSize >= 0, ::Panic(EThrdStackSizeNegative));
1.3568 + if (!aCreateInfo.iHeap)
1.3569 + {// Creating a new heap so verify the parameters.
1.3570 + __ASSERT_ALWAYS(aCreateInfo.iHeapMinSize >= KMinHeapSize,::Panic(EThrdHeapMinTooSmall));
1.3571 + __ASSERT_ALWAYS(aCreateInfo.iHeapMaxSize >= aCreateInfo.iHeapMinSize,::Panic(EThrdHeapMaxLessThanMin));
1.3572 + }
1.3573 +
1.3574 + TInt r = User::ValidateName(*aCreateInfo.iName);
1.3575 + if(KErrNone!=r)
1.3576 + return r;
1.3577 +
1.3578 + SStdEpocThreadCreateInfo8 info;
1.3579 + info.iFunction = aCreateInfo.iFunction;
1.3580 + info.iUserStackSize = aCreateInfo.iStackSize;
1.3581 + info.iUserStack = NULL;
1.3582 + info.iAllocator = aCreateInfo.iHeap;
1.3583 + info.iHeapInitialSize = aCreateInfo.iHeapMinSize;
1.3584 + info.iHeapMaxSize = aCreateInfo.iHeapMaxSize;
1.3585 + info.iPtr = aCreateInfo.iParameter;
1.3586 + info.iTotalSize = sizeof(info);
1.3587 + info.iFlags = aCreateInfo.iAttributes;
1.3588 +
1.3589 + TBuf8<KMaxKernelName> n;
1.3590 + n.Copy(*aCreateInfo.iName);
1.3591 +
1.3592 + return SetReturnedHandle(Exec::ThreadCreate(n, aCreateInfo.iOwner, info),*this);
1.3593 + }
1.3594 +
1.3595 +
1.3596 +EXPORT_C TInt RThread::Create(const TDesC &aName,TThreadFunction aFunction,TInt aStackSize,TInt aHeapMinSize,TInt aHeapMaxSize,TAny *aPtr,TOwnerType aType)
1.3597 +/**
1.3598 +Creates a thread belonging to the current process, and opens this handle
1.3599 +to that thread.
1.3600 +
1.3601 +A new heap is created for this thread.
1.3602 +
1.3603 +By default, ownership of this thread handle is vested in the current process,
1.3604 +but can be vested in the current thread by passing EOwnerThread as
1.3605 +the second parameter to this function.
1.3606 +
1.3607 +If KNullDesC is specified for the name, then an anonymous thread will be created.
1.3608 +Anonymous threads are not global, and cannot be opened by other processes.
1.3609 +
1.3610 +@param aName The name to be assigned to this thread.
1.3611 + KNullDesC, to create an anonymous thread.
1.3612 +@param aFunction A pointer to a function.. Control passes to this function
1.3613 + when the thread is first resumed, i.e. when the thread
1.3614 + is initially scheduled to run.
1.3615 +@param aStackSize The size of the new thread's stack.
1.3616 +@param aHeapMinSize The minimum size for the new thread's heap.
1.3617 +@param aHeapMaxSize The maximum size for the new thread's heap.
1.3618 +@param aPtr A pointer to data to be passed as a parameter to
1.3619 + the thread function when the thread is initially scheduled
1.3620 + to run. If the thread function does not need any data then
1.3621 + this pointer can be NULL. It must be ensured that the memory
1.3622 + pointed to by this pointer is still valid when accessed by
1.3623 + the new thread, e.g. if aPtr points to data on the stack.
1.3624 +@param aType An enumeration whose enumerators define the ownership of
1.3625 + this thread handle. If not explicitly specified,
1.3626 + EOwnerProcess is taken as default.
1.3627 +
1.3628 +@return KErrNone if successful, otherwise one of the other system-wide error codes.
1.3629 + KErrAlreadyExists will be returned if there is another thread in this process with the
1.3630 + specified name.
1.3631 +
1.3632 +@panic USER 109 if aStackSize is negative.
1.3633 +@panic USER 110 if aHeapMinSize is less than KMinHeapSize.
1.3634 +@panic USER 111 if aHeapMaxSize is less than aHeapMinSize.
1.3635 +*/
1.3636 + {
1.3637 + TThreadCreateInfo createInfo(aName, aFunction, aStackSize, aPtr);
1.3638 + createInfo.SetOwner(aType);
1.3639 + createInfo.SetCreateHeap(aHeapMinSize, aHeapMaxSize);
1.3640 + return Create(createInfo);
1.3641 + }
1.3642 +
1.3643 +
1.3644 +
1.3645 +
1.3646 +EXPORT_C TInt RThread::Create(const TDesC& aName, TThreadFunction aFunction, TInt aStackSize, RAllocator* aAllocator, TAny* aPtr, TOwnerType aType)
1.3647 +/**
1.3648 +Creates a thread belonging to the current process, and opens this handle to
1.3649 +that thread.
1.3650 +
1.3651 +This thread uses the heap whose handle is pointed to by
1.3652 +aAllocator. If this is NULL, then the thread uses the heap of the creating thread.
1.3653 +
1.3654 +By default, ownership of this thread handle is vested in the current process,
1.3655 +but can be vested in the current thread by passing EOwnerThread as the second
1.3656 +parameter to this function.
1.3657 +
1.3658 +If KNullDesC is specified for the name, then an anonymous thread will be created.
1.3659 +Anonymous threads are not global, and cannot be opened by other processes.
1.3660 +
1.3661 +@param aName The name to be assigned to this thread.
1.3662 + KNullDesC, to create an anonymous thread.
1.3663 +@param aFunction A pointer to a function. Control passes to this function when
1.3664 + the thread is first resumed, i.e. when the thread is
1.3665 + initially scheduled to run.
1.3666 +@param aStackSize The size of the new thread's stack.
1.3667 +@param aAllocator A pointer to the handle of the heap belonging to another thread
1.3668 + which this thread is to use.
1.3669 +@param aPtr A pointer to data to be passed as a parameter to the thread
1.3670 + function when the thread is initially scheduled to run.
1.3671 + If the thread function does not need any data,
1.3672 + then this pointer can be NULL. It must be ensured that the
1.3673 + memory pointed to by this pointer is still valid when accessed
1.3674 + by the new thread, e.g. if aPtr points to data on the stack.
1.3675 +@param aType An enumeration whose enumerators define the ownership of this
1.3676 + thread handle. If not explicitly specified, EOwnerProcess is
1.3677 + taken as default.
1.3678 +
1.3679 +@return KErrNone if successful otherwise one of the other system-wide error codes.
1.3680 + KErrAlreadyExists will be returned if there is another thread in this process with the
1.3681 + specified name.
1.3682 +
1.3683 +@panic USER 109 if aStackSize is negative.
1.3684 +*/
1.3685 + {
1.3686 + TThreadCreateInfo createInfo(aName, aFunction, aStackSize, aPtr);
1.3687 + createInfo.SetOwner(aType);
1.3688 + createInfo.SetUseHeap(aAllocator);
1.3689 + return Create(createInfo);
1.3690 + }
1.3691 +
1.3692 +
1.3693 +
1.3694 +
1.3695 +EXPORT_C TInt RThread::Open(const TDesC &aName,TOwnerType aType)
1.3696 +/**
1.3697 +Opens a handle to specifically named thread.
1.3698 +
1.3699 +By default, ownership of this thread handle is vested in the
1.3700 +current process, but can be vested in the current thread by passing
1.3701 +EOwnerThread as the second parameter to this function.
1.3702 +
1.3703 +@param aName A reference to the descriptor containing the full name of the
1.3704 + thread that is already running.
1.3705 +@param aType An enumeration whose enumerators define the ownership of this
1.3706 + thread handle. If not explicitly specified, EOwnerProcess is taken
1.3707 + as default.
1.3708 +
1.3709 +@return KErrNone, if successful, otherwise one of the other system-wide
1.3710 + error codes.
1.3711 +*/
1.3712 + {
1.3713 + return OpenByName(aName,aType,EThread);
1.3714 + }
1.3715 +
1.3716 +
1.3717 +
1.3718 +
1.3719 +EXPORT_C TInt RThread::Open(TThreadId aId,TOwnerType aType)
1.3720 +/**
1.3721 +Opens a handle to the thread with a specific thread Id.
1.3722 +
1.3723 +By default, ownership of this thread handle is vested in the
1.3724 +current process, but can be vested in the current thread by passing
1.3725 +EOwnerThread as the second parameter to this function.
1.3726 +
1.3727 +@param aId The thread Id used to find the thread.
1.3728 +@param aType An enumeration whose enumerators define the ownership of this
1.3729 + thread handle. If not explicitly specified, EOwnerProcess is taken
1.3730 + as default.
1.3731 +
1.3732 +@return KErrNone, if successful, otherwise one of the other system-wide
1.3733 + error codes.
1.3734 +*/
1.3735 +//
1.3736 +// Open an already running thread in any process.
1.3737 +//
1.3738 + {
1.3739 +
1.3740 + TUint id=*(TUint*)&aId;
1.3741 + return SetReturnedHandle(Exec::ThreadOpenById(id,aType),*this);
1.3742 + }
1.3743 +
1.3744 +
1.3745 +
1.3746 +
1.3747 +EXPORT_C TInt RThread::Process(RProcess &aProcess) const
1.3748 +/**
1.3749 +Opens a process-relative handle to the process which owns this thread.
1.3750 +
1.3751 +The caller must construct a default RProcess object and pass this to
1.3752 +the function.
1.3753 +On return, aProcess is the open process-relative handle to the process owning
1.3754 +this thread.
1.3755 +
1.3756 +The return value indicates the success or failure of this function.
1.3757 +
1.3758 +@param aProcess A reference to a default RProcess handle; on successful return
1.3759 + from this function, this is the process-relative handle
1.3760 + to the process which owns this thread.
1.3761 +
1.3762 +@return KErrNone, if successful, otherwise one of the other system-wide error
1.3763 + codes.
1.3764 +*/
1.3765 + {
1.3766 + return SetReturnedHandle(Exec::ThreadProcess(iHandle),aProcess);
1.3767 + }
1.3768 +
1.3769 +
1.3770 +
1.3771 +
1.3772 +EXPORT_C TInt User::RenameThread(const TDesC &aName)
1.3773 +/**
1.3774 +Assigns a new name to the current thread, replacing any existing name that
1.3775 +may have been set.
1.3776 +
1.3777 +The new name must be a valid name and it must also be such that the thread's
1.3778 +new fullname remains unique amongst threads.
1.3779 +The length of the new name must be less than or equal to 80 (maximum length of
1.3780 +kernel objects) otherwise a panic is raised.
1.3781 +
1.3782 +@param aName A reference to the descriptor containing the new name for the
1.3783 + thread.
1.3784 +
1.3785 +@return KErrNone if successful, otherwise one of the other system-wide error
1.3786 + codes.
1.3787 +*/
1.3788 + {
1.3789 + TBuf8<KMaxKernelName> name8;
1.3790 + name8.Copy(aName);
1.3791 + return Exec::ThreadRename(KCurrentThreadHandle,name8);
1.3792 + }
1.3793 +
1.3794 +
1.3795 +
1.3796 +
1.3797 +EXPORT_C void RThread::Kill(TInt aReason)
1.3798 +/**
1.3799 +Ends the thread, specifying a reason code.
1.3800 +
1.3801 +This function is dangerous and should be used only in cases where the target
1.3802 +thread cannot end itself via the normal methods of calling User::Exit() or
1.3803 +completing its thread function. A hypothetical example might be where a thread
1.3804 +gets 'stuck' in a third-party DLL.
1.3805 +
1.3806 +The target thread gets no opportunity to execute any clean-up code, therefore
1.3807 +incautious use of this function may lead to memory leaks.
1.3808 +
1.3809 +It is functionally identical to RThread::Terminate(), the only difference
1.3810 +between the two is a legacy distinction between a 'normal' reason for exiting
1.3811 +(use Kill) and an 'abnormal' reason (use Terminate). The choice of function
1.3812 +is reflected in the return value of RThread::ExitType().
1.3813 +
1.3814 +The thread must be in the current process otherwise a panic is raised.
1.3815 +
1.3816 +If the thread is process permanent, or the thread is the last thread in the
1.3817 +process, then the process is also killed. If the thread is system permanent,
1.3818 +the entire system is rebooted.
1.3819 +
1.3820 +WARNING: If the target thread uses a shared heap then use of this function will
1.3821 +cause an internal array used for thread-local storage (TLS) to be leaked. This
1.3822 +leak is specific to ARM platforms which implement the CP15 feature and will
1.3823 +not occur on other platforms.
1.3824 +
1.3825 +@param aReason The reason to be associated with the ending of this thread.
1.3826 +
1.3827 +@see User::Exit()
1.3828 +@see User::SetCritical()
1.3829 +@see User::Critical()
1.3830 +@see RThread::Terminate()
1.3831 +@see RThread::ExitType()
1.3832 +*/
1.3833 + {
1.3834 +
1.3835 + Exec::ThreadKill(iHandle,EExitKill,aReason,NULL);
1.3836 + }
1.3837 +
1.3838 +
1.3839 +
1.3840 +
1.3841 +EXPORT_C void RThread::Terminate(TInt aReason)
1.3842 +/**
1.3843 +Ends the thread, specifying a reason code.
1.3844 +
1.3845 +This function is dangerous and should be used only in cases where the target
1.3846 +thread cannot end itself via the normal methods of calling User::Exit() or
1.3847 +completing its thread function. A hypothetical example might be where a thread
1.3848 +gets 'stuck' in a third-party DLL.
1.3849 +
1.3850 +The target thread gets no opportunity to execute any clean-up code, therefore
1.3851 +incautious use of this function may lead to memory leaks.
1.3852 +
1.3853 +It is functionally identical to RThread::Kill(), the only difference
1.3854 +between the two is a legacy distinction between a 'normal' reason for exiting
1.3855 +(use Kill) and an 'abnormal' reason (use Terminate). The choice of function
1.3856 +is reflected in the return value of RThread::ExitType().
1.3857 +
1.3858 +The thread must be in the current process otherwise a panic is raised.
1.3859 +
1.3860 +If the thread is process critical or process permanent, or the thread is the
1.3861 +last thread in the process, then the process is also terminated. If the thread
1.3862 +is system critical or system permanent, the entire system is rebooted.
1.3863 +
1.3864 +WARNING: If the target thread uses a shared heap then use of this function will
1.3865 +cause an internal array used for thread-local storage (TLS) to be leaked. This
1.3866 +leak is specific to ARM platforms which implement the CP15 feature and will
1.3867 +not occur on other platforms.
1.3868 +
1.3869 +@param aReason The reason to be associated with the ending of this thread.
1.3870 +
1.3871 +@see User::Exit()
1.3872 +@see User::SetCritical()
1.3873 +@see User::Critical()
1.3874 +@see RThread::Kill()
1.3875 +@see RThread::ExitType()
1.3876 +*/
1.3877 + {
1.3878 +
1.3879 + Exec::ThreadKill(iHandle,EExitTerminate,aReason,NULL);
1.3880 + }
1.3881 +
1.3882 +
1.3883 +
1.3884 +
1.3885 +EXPORT_C void RThread::Panic(const TDesC &aCategory,TInt aReason)
1.3886 +/**
1.3887 +Panics this thread, specifying the panic category name and reason.
1.3888 +
1.3889 +The length of the category name should be no greater than 16; any name with
1.3890 +a length greater than 16 is truncated to 16.
1.3891 +
1.3892 +The calling thread, i.e. the thread in which this function is called, must be
1.3893 +in the same process as this target thread, otherwise the calling thread
1.3894 +is itself panicked.
1.3895 +
1.3896 +If the thread is process critical or process permanent, the process also panics.
1.3897 +If the thread is system critical or system permanent, the entire system is
1.3898 +rebooted.
1.3899 +
1.3900 +@param aCategory A reference to the descriptor containing the text which defines
1.3901 + the category name for this panic.
1.3902 +@param aReason The panic number.
1.3903 +
1.3904 +@panic KERN-EXEC 46 if this target thread's process is not the same as the
1.3905 + calling thread's process.
1.3906 +
1.3907 +@see User::SetCritical()
1.3908 +@see User::Critical()
1.3909 +*/
1.3910 + {
1.3911 +
1.3912 + TBuf8<KMaxExitCategoryName> cat;
1.3913 + TInt len = aCategory.Length();
1.3914 + if(len>KMaxExitCategoryName)
1.3915 + {
1.3916 + TPtr aCatPtr((TUint16*)aCategory.Ptr(),KMaxExitCategoryName,KMaxExitCategoryName);
1.3917 + cat.Copy(aCatPtr);
1.3918 + }
1.3919 + else
1.3920 + cat.Copy(aCategory);
1.3921 + Exec::ThreadKill(iHandle,EExitPanic,aReason,&cat);
1.3922 + }
1.3923 +
1.3924 +
1.3925 +
1.3926 +
1.3927 +EXPORT_C void RThread::Logon(TRequestStatus &aStatus) const
1.3928 +/**
1.3929 +Requests notification when this thread dies, normally or otherwise.
1.3930 +
1.3931 +A request for notification is an asynchronous request, and completes:
1.3932 +
1.3933 +- when the thread terminates
1.3934 +- if the outstanding request is cancelled by a call to RThread::LogonCancel().
1.3935 +
1.3936 +A request for notification requires memory to be allocated; if this is
1.3937 +unavailable, then the call to Logon() returns, and the asynchronous request
1.3938 +completes immediately.
1.3939 +
1.3940 +Note that even when a thread has died, it is not possible to create a new thread with the same name
1.3941 +until all handles on the dead thread have been closed. If this is attempted, the call to
1.3942 +RThread::Create will fail with KErrAlreadyExists.
1.3943 +
1.3944 +@param aStatus A reference to the request status object.
1.3945 + This contains the reason code describing the reason for
1.3946 + the termination of the thread, i.e. the value returned by a call to RThread::ExitReason().
1.3947 + Alternatively, this is set to:
1.3948 + KErrCancel, if an outstanding request is cancelled;
1.3949 + KErrNoMemory, if there is insufficient memory to deal with the request.
1.3950 +
1.3951 +@see RThread::LogonCancel()
1.3952 +@see RThread::ExitReason()
1.3953 +@see RThread::Create()
1.3954 +*/
1.3955 + {
1.3956 +
1.3957 + aStatus=KRequestPending;
1.3958 + Exec::ThreadLogon(iHandle,&aStatus,EFalse);
1.3959 + }
1.3960 +
1.3961 +
1.3962 +
1.3963 +
1.3964 +EXPORT_C TInt RThread::LogonCancel(TRequestStatus &aStatus) const
1.3965 +/**
1.3966 +Cancels an outstanding request for notification of the death of this thread.
1.3967 +
1.3968 +A request for notification must previously have been made, otherwise
1.3969 +the function returns KErrGeneral.
1.3970 +
1.3971 +The caller passes a reference to the same request status object as was passed
1.3972 +in the original call to Logon().
1.3973 +
1.3974 +@param aStatus A reference to the same request status object used in
1.3975 + the original call to Logon().
1.3976 +
1.3977 +@return KErrGeneral, if there is no outstanding request, KErrNone otherwise.
1.3978 +*/
1.3979 + {
1.3980 + return Exec::ThreadLogonCancel(iHandle,&aStatus,EFalse);
1.3981 + }
1.3982 +
1.3983 +
1.3984 +
1.3985 +
1.3986 +/**
1.3987 +Creates a Rendezvous request with the thread.
1.3988 +
1.3989 +The request is an asynchronous request, and completes:
1.3990 +
1.3991 +- when the thread next calls RThread::Rendezvous(TInt aReason)
1.3992 +- if the outstanding request is cancelled by a call to RThread::RendezvousCancel()
1.3993 +- if the thread exits
1.3994 +- if the thread panics.
1.3995 +
1.3996 +Note that a request requires memory to be allocated; if this is unavailable,
1.3997 +then this call to Rendezvous() returns, and the asynchronous request
1.3998 +completes immediately.
1.3999 +
1.4000 +@param aStatus A reference to the request status object.
1.4001 + The Rendezvous completes normally when
1.4002 + RThread::Rendezvous(TInt aReason) is called, and this
1.4003 + request status object will contain this reason code.
1.4004 + If the thread exits or panics, then this is the thread exit
1.4005 + reason value, i.e. the same value returned by RThread::ExitReason().
1.4006 + Alternatively, this is set to:
1.4007 + KErrCancel, if an outstanding request is cancelled;
1.4008 + KErrNoMemory, if there is insufficient memory to deal with the request.
1.4009 +
1.4010 +@see RThread::Rendezvous(TInt aReason)
1.4011 +@see RThread::RendezvousCancel(TRequestStatus& aStatus)
1.4012 +*/
1.4013 +EXPORT_C void RThread::Rendezvous(TRequestStatus& aStatus) const
1.4014 +
1.4015 + {
1.4016 + aStatus=KRequestPending;
1.4017 + Exec::ThreadLogon(iHandle,&aStatus,ETrue);
1.4018 + }
1.4019 +
1.4020 +
1.4021 +
1.4022 +
1.4023 +/**
1.4024 +Cancels a previously requested Rendezvous with the thread
1.4025 +
1.4026 +The request completes with the value KErrCancel (if it was still outstanding).
1.4027 +
1.4028 +@param aStatus A reference to the same request status object used in
1.4029 + the original call to Rendezvous(TRequestStatus& aStatus).
1.4030 +
1.4031 +@return KErrGeneral, if there is no outstanding request, KErrNone otherwise.
1.4032 +
1.4033 +@see RThread::Rendezvous(TRequestStatus& aStatus)
1.4034 +*/
1.4035 +EXPORT_C TInt RThread::RendezvousCancel(TRequestStatus& aStatus) const
1.4036 + {
1.4037 + return Exec::ThreadLogonCancel(iHandle,&aStatus,ETrue);
1.4038 + }
1.4039 +
1.4040 +
1.4041 +
1.4042 +
1.4043 +/**
1.4044 +Completes all Rendezvous' with the current thread.
1.4045 +
1.4046 +@param aReason The reason code used to complete all rendezvous requests
1.4047 +
1.4048 +@see RThread::Rendezvous(TRequestStatus& aStatus)
1.4049 +*/
1.4050 +EXPORT_C void RThread::Rendezvous(TInt aReason)
1.4051 + {
1.4052 + Exec::ThreadRendezvous(aReason);
1.4053 + }
1.4054 +
1.4055 +
1.4056 +
1.4057 +
1.4058 +EXPORT_C TBusLocalDrive::TBusLocalDrive()
1.4059 +//
1.4060 +// Constructor
1.4061 +//
1.4062 + : iStatus(KErrNotReady)
1.4063 + {}
1.4064 +
1.4065 +
1.4066 +
1.4067 +
1.4068 +EXPORT_C TInt TBusLocalDrive::Read(TInt64 aPos,TInt aLength,const TAny* aTrg,TInt aThreadHandle,TInt aOffset,TInt aFlags)
1.4069 +//
1.4070 +// Read from the connected drive, and pass flags to driver
1.4071 +//
1.4072 + {
1.4073 + return RLocalDrive::Read(aPos,aLength,aTrg,aThreadHandle,aOffset,aFlags);
1.4074 + }
1.4075 +
1.4076 +
1.4077 +
1.4078 +
1.4079 +EXPORT_C TInt TBusLocalDrive::Read(TInt64 aPos,TInt aLength,const TAny* aTrg,TInt aThreadHandle,TInt anOffset)
1.4080 +//
1.4081 +// Read from the connected drive.
1.4082 +//
1.4083 + {
1.4084 +
1.4085 + return RLocalDrive::Read(aPos,aLength,aTrg,aThreadHandle,anOffset);
1.4086 + }
1.4087 +
1.4088 +
1.4089 +
1.4090 +
1.4091 +EXPORT_C TInt TBusLocalDrive::Write(TInt64 aPos,TInt aLength,const TAny* aSrc,TInt aThreadHandle,TInt aOffset,TInt aFlags)
1.4092 +//
1.4093 +// Write to the connected drive and pass flags to driver
1.4094 +//
1.4095 + {
1.4096 +
1.4097 + return RLocalDrive::Write(aPos,aLength,aSrc,aThreadHandle,aOffset,aFlags);
1.4098 + }
1.4099 +
1.4100 +
1.4101 +
1.4102 +
1.4103 +EXPORT_C TInt TBusLocalDrive::Write(TInt64 aPos,TInt aLength,const TAny* aSrc,TInt aThreadHandle,TInt anOffset)
1.4104 +//
1.4105 +// Write to the connected drive.
1.4106 +//
1.4107 + {
1.4108 +
1.4109 + return RLocalDrive::Write(aPos,aLength,aSrc,aThreadHandle,anOffset);
1.4110 + }
1.4111 +
1.4112 +
1.4113 +
1.4114 +
1.4115 +EXPORT_C TInt TBusLocalDrive::Read(TInt64 aPos,TInt aLength,TDes8& aTrg)
1.4116 +//
1.4117 +// Read from the connected drive.
1.4118 +//
1.4119 + {
1.4120 +
1.4121 + return RLocalDrive::Read(aPos,aLength,aTrg);
1.4122 + }
1.4123 +
1.4124 +
1.4125 +
1.4126 +
1.4127 +EXPORT_C TInt TBusLocalDrive::Write(TInt64 aPos,const TDesC8& aSrc)
1.4128 +//
1.4129 +// Write to the connected drive.
1.4130 +//
1.4131 + {
1.4132 +
1.4133 + return RLocalDrive::Write(aPos,aSrc);
1.4134 + }
1.4135 +
1.4136 +
1.4137 +
1.4138 +
1.4139 +EXPORT_C TInt TBusLocalDrive::Caps(TDes8& anInfo)
1.4140 +//
1.4141 +// Get the connected drive's capabilities info.
1.4142 +//
1.4143 + {
1.4144 +
1.4145 + return RLocalDrive::Caps(anInfo);
1.4146 + }
1.4147 +
1.4148 +
1.4149 +
1.4150 +
1.4151 +const TInt KDefaultMaxBytesPerFormat=0x00004000;// 16K
1.4152 +const TInt KFormatSectorSize=0x00000200; // 512
1.4153 +const TInt KFormatSectorShift=9;
1.4154 +
1.4155 +EXPORT_C TInt TBusLocalDrive::Format(TFormatInfo &anInfo)
1.4156 +//
1.4157 +// Format the connected drive.
1.4158 +//
1.4159 + {
1.4160 + if (anInfo.i512ByteSectorsFormatted<0)
1.4161 + return KErrArgument;
1.4162 + if (!anInfo.iFormatIsCurrent)
1.4163 + {
1.4164 + anInfo.iFormatIsCurrent=ETrue;
1.4165 + anInfo.i512ByteSectorsFormatted=0;
1.4166 + anInfo.iMaxBytesPerFormat=KDefaultMaxBytesPerFormat;
1.4167 +
1.4168 + // Get the capabilities of the drive. If extra info is supported,
1.4169 + // Then overrise the default KMaxBytesPerFormat
1.4170 + TLocalDriveCapsV3Buf caps;
1.4171 + Caps(caps);
1.4172 + anInfo.iMaxBytesPerFormat = caps().iMaxBytesPerFormat ? caps().iMaxBytesPerFormat : KDefaultMaxBytesPerFormat;
1.4173 + }
1.4174 + TInt64 pos=TInt64(anInfo.i512ByteSectorsFormatted)<<KFormatSectorShift;
1.4175 + TInt length=anInfo.iMaxBytesPerFormat;
1.4176 + TInt r=RLocalDrive::Format(pos,length);
1.4177 +
1.4178 + // A positive return code specifies that the format step
1.4179 + // has been adjusted (possibly to account for the partition offset)
1.4180 + if(r > 0)
1.4181 + {
1.4182 + length = r;
1.4183 + r = KErrNone;
1.4184 + }
1.4185 +
1.4186 + if (r==KErrNone)
1.4187 + {
1.4188 + length+=KFormatSectorSize-1;
1.4189 + length>>=KFormatSectorShift;
1.4190 + anInfo.i512ByteSectorsFormatted+=length;
1.4191 + }
1.4192 +
1.4193 + if (r==KErrEof)
1.4194 + anInfo.iFormatIsCurrent=EFalse;
1.4195 +
1.4196 + return r;
1.4197 + }
1.4198 +
1.4199 +
1.4200 +
1.4201 +
1.4202 +EXPORT_C TInt TBusLocalDrive::Format(TInt64 aPos, TInt aLength)
1.4203 +//
1.4204 +// Format the connected drive.
1.4205 +//
1.4206 + {
1.4207 + TInt r = KErrNone;
1.4208 +
1.4209 + do
1.4210 + {
1.4211 + if((r = RLocalDrive::Format(aPos, aLength)) > 0)
1.4212 + {
1.4213 + aPos += r;
1.4214 + aLength -= r;
1.4215 + if (aLength == 0)
1.4216 + r = KErrNone;
1.4217 + }
1.4218 + }
1.4219 + while(r > 0);
1.4220 + return(r);
1.4221 + }
1.4222 +
1.4223 +
1.4224 +
1.4225 +
1.4226 +EXPORT_C TInt TBusLocalDrive::ControlIO(TInt aCommand, TAny* aParam1, TAny* aParam2)
1.4227 +//
1.4228 +// Control IO
1.4229 +// NB: If in a data-paging environment and this drive is the data-paging drive, this API will
1.4230 +// return KErrNotSupported if either aParam1 or aParam2 are non-NULL to avoid the possibility
1.4231 +// of taking a data paging fault in the media driver's thread.
1.4232 +// For this reason, this function has been deprecated
1.4233 +
1.4234 +// @deprecated Callers of this function should use one of the other overloads
1.4235 +//
1.4236 + {
1.4237 + return(RLocalDrive::ControlIO(aCommand,aParam1,aParam2));
1.4238 + }
1.4239 +
1.4240 +
1.4241 +EXPORT_C TInt TBusLocalDrive::ControlIO(TInt aCommand, TDes8& aBuf, TInt aParam)
1.4242 +//
1.4243 +// Control IO
1.4244 +// In a data-paging environment, this API allows the passed descriptor to be pinned in the context
1.4245 +// of the client's thread to avoid taking a data paging fault in the media driver's thread
1.4246 +//
1.4247 + {
1.4248 + if (aBuf.MaxLength() == 0)
1.4249 + return KErrArgument;
1.4250 + return(RLocalDrive::ControlIO(aCommand, aBuf, aParam));
1.4251 + }
1.4252 +
1.4253 +
1.4254 +EXPORT_C TInt TBusLocalDrive::ControlIO(TInt aCommand, TDesC8& aBuf, TInt aParam)
1.4255 +//
1.4256 +// Control IO
1.4257 +// In a data-paging environment, this API allows the passed descriptor to be pinned in the context
1.4258 +// of the client's thread to avoid taking a data paging fault in the media driver's thread
1.4259 +//
1.4260 + {
1.4261 + if (aBuf.Length() == 0)
1.4262 + return KErrArgument;
1.4263 + return(RLocalDrive::ControlIO(aCommand, aBuf, aParam));
1.4264 + }
1.4265 +
1.4266 +EXPORT_C TInt TBusLocalDrive::ControlIO(TInt aCommand, TInt aParam1, TInt aParam2)
1.4267 + {
1.4268 + return(RLocalDrive::ControlIO(aCommand, aParam1, aParam2));
1.4269 + }
1.4270 +
1.4271 +
1.4272 +
1.4273 +EXPORT_C TInt TBusLocalDrive::SetMountInfo(const TDesC8* aMountInfo,TInt aMessageHandle)
1.4274 +//
1.4275 +// Set the mount information on the local drive
1.4276 +//
1.4277 + {
1.4278 +
1.4279 + return RLocalDrive::SetMountInfo(aMountInfo,aMessageHandle);
1.4280 + }
1.4281 +
1.4282 +
1.4283 +
1.4284 +
1.4285 +EXPORT_C TInt TBusLocalDrive::ForceRemount(TUint aFlags)
1.4286 +//
1.4287 +// Force a remount on the local drive
1.4288 +//
1.4289 + {
1.4290 +
1.4291 + TInt err = RLocalDrive::ForceMediaChange(aFlags);
1.4292 + if(err != KErrNone)
1.4293 + return err;
1.4294 +
1.4295 + if(aFlags & ELocDrvRemountForceMediaChange)
1.4296 + err = CheckMount();
1.4297 +
1.4298 + return err;
1.4299 + }
1.4300 +
1.4301 +
1.4302 +
1.4303 +
1.4304 +EXPORT_C TInt TBusLocalDrive::GetLastErrorInfo(TDes8& aErrorInfo)
1.4305 +//
1.4306 +// Get information on the local drives last error
1.4307 +//
1.4308 + {
1.4309 +
1.4310 + return RLocalDrive::GetLastErrorInfo(aErrorInfo);
1.4311 + }
1.4312 +
1.4313 +
1.4314 +
1.4315 +
1.4316 +EXPORT_C TLocalDriveCaps::TLocalDriveCaps()
1.4317 +//
1.4318 +// Constructor
1.4319 +//
1.4320 + : iSize(0),
1.4321 + iType(EMediaNotPresent),
1.4322 + iConnectionBusType(EConnectionBusInternal),
1.4323 + iDriveAtt(0),
1.4324 + iMediaAtt(0),
1.4325 + iBaseAddress(NULL),
1.4326 + iFileSystemId(0)
1.4327 + {}
1.4328 +
1.4329 +
1.4330 +
1.4331 +
1.4332 +/**
1.4333 +@capability TCB
1.4334 +*/
1.4335 +EXPORT_C TInt TBusLocalDrive::Connect(TInt aDriveNumber,TBool &aChangedFlag)
1.4336 +//
1.4337 +// Connect to the drive.
1.4338 +//
1.4339 + {
1.4340 +
1.4341 + return RLocalDrive::Connect(aDriveNumber, aChangedFlag);
1.4342 + }
1.4343 +
1.4344 +
1.4345 +
1.4346 +
1.4347 +EXPORT_C void TBusLocalDrive::Disconnect()
1.4348 +//
1.4349 +// Disconnect from the drive.
1.4350 +//
1.4351 + {
1.4352 +
1.4353 + Close();
1.4354 + }
1.4355 +
1.4356 +
1.4357 +
1.4358 +
1.4359 +EXPORT_C TInt TBusLocalDrive::Enlarge(TInt aLength)
1.4360 +//
1.4361 +// Increase the size of the connected drive by the specified length (in bytes).
1.4362 +//
1.4363 + {
1.4364 +
1.4365 + return RLocalDrive::Enlarge(aLength);
1.4366 + }
1.4367 +
1.4368 +
1.4369 +
1.4370 +
1.4371 +EXPORT_C TInt TBusLocalDrive::ReduceSize(TInt aPos,TInt aLength)
1.4372 +//
1.4373 +// Reduce the size of the connected drive by removing the specified length
1.4374 +// (in bytes) starting at the specified position.
1.4375 +//
1.4376 + {
1.4377 +
1.4378 + return RLocalDrive::Reduce(aPos, aLength);
1.4379 + }
1.4380 +
1.4381 +
1.4382 +
1.4383 +
1.4384 +/**
1.4385 +Attempt to unlock a password-enabled drive and optionally store the password in the password store.
1.4386 +
1.4387 +@param aPassword A descriptor containing the password data.
1.4388 +@param aStorePassword If ETrue, the password is added to the password store.
1.4389 +
1.4390 +@return KErrNone, if successful.
1.4391 + KErrAlreadyExists, if the drive is already unlocked.
1.4392 + KErrAccessDenied, if the drive unlock operation fails.
1.4393 +
1.4394 +@see TBusLocalDrive::SetPassword
1.4395 +@see TBusLocalDrive::Clear
1.4396 +@see TBusLocalDrive::ErasePassword
1.4397 +*/
1.4398 +EXPORT_C TInt TBusLocalDrive::Unlock(const TDesC8& aPassword, TBool aStorePassword)
1.4399 + {
1.4400 + TInt err = CheckMount();
1.4401 + if (err != KErrNone)
1.4402 + return err;
1.4403 +
1.4404 + if (!(Status() & KMediaAttLocked))
1.4405 + return KErrAlreadyExists;
1.4406 +
1.4407 + err = RLocalDrive::Unlock(aPassword, aStorePassword);
1.4408 +
1.4409 + if(err == KErrLocked)
1.4410 + err = KErrAccessDenied;
1.4411 +
1.4412 + return err;
1.4413 + }
1.4414 +
1.4415 +
1.4416 +
1.4417 +
1.4418 +/**
1.4419 +Attempt to lock password-enabled drive and optionally store the new password in the password store.
1.4420 +
1.4421 +@param aOldPassword A descriptor containing old password.
1.4422 +@param aNewPassword A descriptor containing new password.
1.4423 +@param aStorePassword If ETrue, the password is added to the password store.
1.4424 +
1.4425 +@return KErrNone, if successful.
1.4426 + KErrAccessDenied, if the drive is already locked or the old password is incorrect.
1.4427 +
1.4428 +@see TBusLocalDrive::Unlock
1.4429 +@see TBusLocalDrive::Clear
1.4430 +@see TBusLocalDrive::ErasePassword
1.4431 +*/
1.4432 +EXPORT_C TInt TBusLocalDrive::SetPassword(const TDesC8& aOldPassword, const TDesC8& aNewPassword, TBool aStorePassword)
1.4433 + {
1.4434 + TInt err = CheckMount();
1.4435 + if (err != KErrNone)
1.4436 + return err;
1.4437 +
1.4438 + if (Status() & KMediaAttLocked)
1.4439 + return KErrAccessDenied;
1.4440 +
1.4441 + err = RLocalDrive::SetPassword(aOldPassword, aNewPassword, aStorePassword);
1.4442 + if(err == KErrLocked)
1.4443 + err = KErrAccessDenied;
1.4444 +
1.4445 + return err;
1.4446 + }
1.4447 +
1.4448 +
1.4449 +
1.4450 +
1.4451 +/**
1.4452 +Clears a password from a card - controller sets password to null.
1.4453 +volume will not be password-enabled next time it is powered up.
1.4454 +The password is cleared from the password store.
1.4455 +
1.4456 +@param aPassword A descriptor containing the password.
1.4457 +
1.4458 +@return KErrNone, if successful.
1.4459 + KErrAccessDenied, if the drive is already locked or the password is incorrect.
1.4460 +
1.4461 +@see TBusLocalDrive::Unlock
1.4462 +@see TBusLocalDrive::SetPassword
1.4463 +@see TBusLocalDrive::ErasePassword
1.4464 +*/
1.4465 +EXPORT_C TInt TBusLocalDrive::Clear(const TDesC8& aPassword)
1.4466 + {
1.4467 + TInt err = CheckMount();
1.4468 + if (err != KErrNone)
1.4469 + return err;
1.4470 +
1.4471 + if (Status() & KMediaAttLocked)
1.4472 + return KErrAccessDenied;
1.4473 +
1.4474 + err = RLocalDrive::Clear(aPassword);
1.4475 + if(err == KErrLocked)
1.4476 + err = KErrAccessDenied;
1.4477 +
1.4478 + return err;
1.4479 + }
1.4480 +
1.4481 +
1.4482 +
1.4483 +
1.4484 +/**
1.4485 +Forcibly unlock a password-enabled drive.
1.4486 +KErrAccessDenied is returned if the drive is already mounted (and therefore unlocked)
1.4487 +or if the drive is not already mounted and the operation fails.
1.4488 +
1.4489 +@return KErrNone, if successful.
1.4490 + KErrAccessDenied, if the drive is not locked or the operation is not supported.
1.4491 +
1.4492 +@see TBusLocalDrive::Unlock
1.4493 +@see TBusLocalDrive::SetPassword
1.4494 +@see TBusLocalDrive::ErasePassword
1.4495 +*/
1.4496 +EXPORT_C TInt TBusLocalDrive::ErasePassword()
1.4497 + {
1.4498 + TInt err = CheckMount();
1.4499 + if (err != KErrNone)
1.4500 + return err;
1.4501 +
1.4502 + if (!(Status() & KMediaAttLocked))
1.4503 + return KErrAccessDenied;
1.4504 +
1.4505 + err = RLocalDrive::ErasePassword();
1.4506 + if(err != KErrNone)
1.4507 + err = KErrAccessDenied;
1.4508 +
1.4509 + return err;
1.4510 + }
1.4511 +
1.4512 +
1.4513 +
1.4514 +
1.4515 +TInt TBusLocalDrive::CheckMount()
1.4516 +//
1.4517 +// Check the local drive can be, or is mounted
1.4518 +//
1.4519 + {
1.4520 + TLocalDriveCaps caps;
1.4521 + TPckg<TLocalDriveCaps> capsPckg(caps);
1.4522 + TInt err = RLocalDrive::Caps(capsPckg);
1.4523 + iStatus = caps.iMediaAtt;
1.4524 + return err;
1.4525 + }
1.4526 +
1.4527 +
1.4528 +
1.4529 +/**
1.4530 +Write the password store to the peripheral bus controller.
1.4531 +
1.4532 +@return
1.4533 + - KErrNone if Successful
1.4534 + - KErrOverflow If aBuf is longer than TPasswordStore::EMaxPasswordLength
1.4535 + - KErrCorrupt If store in aBuf is malformed.
1.4536 +
1.4537 +@param aBuf Data to replace the current password store.
1.4538 +*/
1.4539 +EXPORT_C TInt TBusLocalDrive::WritePasswordData(const TDesC8& aBuf)
1.4540 + {
1.4541 + return RLocalDrive::WritePasswordData(aBuf);
1.4542 + }
1.4543 +
1.4544 +
1.4545 +
1.4546 +
1.4547 +EXPORT_C TInt TBusLocalDrive::ReadPasswordData(TDes8& aBuf)
1.4548 +//
1.4549 +// Read the entire password store from the peripheral bus controller.
1.4550 +//
1.4551 + {
1.4552 + return RLocalDrive::ReadPasswordData(aBuf);
1.4553 + }
1.4554 +
1.4555 +
1.4556 +
1.4557 +
1.4558 +EXPORT_C TInt TBusLocalDrive::PasswordStoreLengthInBytes()
1.4559 +//
1.4560 +// Return the number of bytes used by peripheral bus controller password store.
1.4561 +//
1.4562 + {
1.4563 + return RLocalDrive::PasswordStoreLengthInBytes();
1.4564 + }
1.4565 +
1.4566 +
1.4567 +
1.4568 +
1.4569 +EXPORT_C TInt TBusLocalDrive::DeleteNotify(TInt64 aPos, TInt aLength)
1.4570 +//
1.4571 +// Notify the media driver that an area of the partition has been deleted.
1.4572 +// This is used by certain media (e.g NAND flash) for garbage collection.
1.4573 +//
1.4574 + {
1.4575 + return RLocalDrive::DeleteNotify(aPos, aLength);
1.4576 + }
1.4577 +
1.4578 +
1.4579 +/**
1.4580 +Query a property of the media device
1.4581 +
1.4582 +@prototype
1.4583 +@internalTechnology
1.4584 +*/
1.4585 +EXPORT_C TInt TBusLocalDrive::QueryDevice(TQueryDevice aQueryDevice, TDes8 &aBuf)
1.4586 + {
1.4587 + return RLocalDrive::QueryDevice(aQueryDevice, aBuf);
1.4588 + }
1.4589 +
1.4590 +
1.4591 +EXPORT_C void User::__DbgMarkStart(TBool aKernel)
1.4592 +/**
1.4593 +Marks the start of heap cell checking for the current thread's default heap,
1.4594 +or for the kernel heap.
1.4595 +
1.4596 +If earlier calls to __DbgMarkStart() have been made, then this
1.4597 +call to __DbgMarkStart() marks the start of a new nested level of
1.4598 +heap cell checking.
1.4599 +
1.4600 +Every call to __DbgMarkStart() should be matched by a later call
1.4601 +to __DbgMarkEnd() to verify that the number of heap cells allocated, at
1.4602 +the current nested level, is as expected.
1.4603 +This expected number of heap cells is passed to __DbgMarkEnd()
1.4604 +as a parameter; however, the most common expected number is zero, reflecting
1.4605 +the fact that the most common requirement is to check that all memory allocated
1.4606 +since a previous call to __DbgStartCheck() has been freed.
1.4607 +
1.4608 +@param aKernel ETrue, if checking is being done for the kernel heap;
1.4609 + EFalse, if checking is being done for the current thread's
1.4610 + default heap.
1.4611 +*/
1.4612 + {
1.4613 +
1.4614 + if (aKernel)
1.4615 + Exec::KernelHeapDebug(EDbgMarkStart,0,NULL);
1.4616 + else
1.4617 + GetHeap()->__DbgMarkStart();
1.4618 + }
1.4619 +
1.4620 +
1.4621 +
1.4622 +
1.4623 +EXPORT_C void User::__DbgMarkCheck(TBool aKernel, TBool aCountAll, TInt aCount, const TUint8* aFileName, TInt aLineNum)
1.4624 +//
1.4625 +// Call CheckNum for the default heap
1.4626 +//
1.4627 +/**
1.4628 +Checks the current number of allocated heap cells for the current thread's default
1.4629 +heap, or the kernel heap.
1.4630 +
1.4631 +If aCountAll is true, the function checks that the total number of
1.4632 +allocated cells on the heap is the same as aCount. If aCountAll is false,
1.4633 +the function checks that the number of allocated cells at the current nested
1.4634 +level is the same as aCount.
1.4635 +
1.4636 +If checking fails, the function raises a panic. Information about the failure
1.4637 +is put into the panic category, which takes the form:
1.4638 +
1.4639 +ALLOC COUNT\\rExpected aaa\\rAllocated bbb\\rLn: ccc ddd
1.4640 +
1.4641 +Where aaa is the value aCount, bbb is the number of allocated heap cells,
1.4642 +ccc is a line number, copied from aLineNum, and ddd is a file name, copied
1.4643 +from the descriptor aFileName.
1.4644 +
1.4645 +Note that the panic number is 1.
1.4646 +
1.4647 +@param aKernel ETrue, if checking is being done for the kernel heap;
1.4648 + EFalse, if checking is being done for the current thread's
1.4649 + default heap.
1.4650 +@param aCountAll If true, the function checks that the total number of
1.4651 + allocated cells on the heap is the same as aCount.
1.4652 + If false, the function checks that the number of allocated
1.4653 + cells at the current nested level is the same as aCount.
1.4654 +@param aCount The expected number of allocated cells.
1.4655 +@param aFileName A filename; this is displayed as part of the panic category,
1.4656 + if the check fails.
1.4657 +@param aLineNum A line number; this is displayed as part of the panic category,
1.4658 + if the check fails.
1.4659 +*/
1.4660 + {
1.4661 +
1.4662 + if (!aKernel)
1.4663 + GetHeap()->__DbgMarkCheck(aCountAll,aCount,aFileName,aLineNum);
1.4664 + else
1.4665 + {
1.4666 + TPtrC8 filename(aFileName);
1.4667 + TKernelHeapMarkCheckInfo info;
1.4668 + info.iCountAll=aCountAll;
1.4669 + info.iFileName=&filename;
1.4670 + info.iLineNum=aLineNum;
1.4671 + Exec::KernelHeapDebug(EDbgMarkCheck,aCount,&info);
1.4672 + }
1.4673 + }
1.4674 +
1.4675 +
1.4676 +
1.4677 +
1.4678 +EXPORT_C TUint32 User::__DbgMarkEnd(TBool aKernel, TInt aCount)
1.4679 +//
1.4680 +// Call CheckHeap for the default heap
1.4681 +//
1.4682 +/**
1.4683 +Marks the end of heap cell checking at the current nested level for the current
1.4684 +thread's default heap, or the kernel heap.
1.4685 +
1.4686 +The function checks that the number of heap cells allocated, at the current
1.4687 +nested level, is aCount. The most common value for aCount is zero, reflecting
1.4688 +the fact that the most common requirement is to check that all memory allocated
1.4689 +since a previous call to __DbgStartCheck() has been freed.
1.4690 +
1.4691 +A call to this function should match an earlier call to __DbgMarkStart().
1.4692 +If there are more calls to this function than calls to __DbgMarkStart(), then
1.4693 +this function raises a USER 51 panic.
1.4694 +
1.4695 +If the check fails for a user heap, the function raises an ALLOC: nnnnnnnn
1.4696 +panic, where nnnnnnnn is a hexadecimal pointer to the first orphaned heap
1.4697 +cell.
1.4698 +
1.4699 +If the check fails for the kernel heap, the kernel server raises a KERN-EXEC 17
1.4700 +panic.
1.4701 +
1.4702 +@param aKernel ETrue, if checking is being done for the kernel heap;
1.4703 + EFalse, if checking is being done for the current thread's
1.4704 + default heap.
1.4705 +@param aCount The number of allocated heap cells expected.
1.4706 +
1.4707 +@return Zero always.
1.4708 +*/
1.4709 + {
1.4710 +
1.4711 + if (!aKernel)
1.4712 + {
1.4713 + TUint32 badCell=GetHeap()->__DbgMarkEnd(aCount);
1.4714 + if (badCell!=0)
1.4715 + {
1.4716 + TBuf<0x10> info=_L("ALLOC: ");
1.4717 + info.AppendFormat(_L("%x\n"), badCell);
1.4718 + User::Panic(info,0);
1.4719 + }
1.4720 + return(badCell);
1.4721 + }
1.4722 + else
1.4723 + Exec::KernelHeapDebug(EDbgMarkEnd,aCount,NULL);
1.4724 + return(0);
1.4725 + }
1.4726 +
1.4727 +
1.4728 +
1.4729 +
1.4730 +EXPORT_C void User::__DbgSetAllocFail(TBool aKernel, RAllocator::TAllocFail aType, TInt aRate)
1.4731 +//
1.4732 +// Set the failure rate for allocating from the default user heap
1.4733 +//
1.4734 +/**
1.4735 +Simulates a heap allocation failure for the current thread's default heap,
1.4736 +or the kernel heap.
1.4737 +
1.4738 +The failure occurs on subsequent calls to new or any of the functions which
1.4739 +allocate memory from the heap.
1.4740 +
1.4741 +The timing of the allocation failure depends on the type of allocation failure
1.4742 +requested, i.e. on the value of aType.
1.4743 +
1.4744 +The simulation of heap allocation failure is cancelled if aType is given
1.4745 +the value RAllocator::ENone.
1.4746 +
1.4747 +Notes:
1.4748 +
1.4749 +1. If the failure type is RHeap::EFailNext, the next attempt to allocate from
1.4750 + the heap fails; however, no further failures will occur.
1.4751 +
1.4752 +2. For failure types RHeap::EFailNext and RHeap::ENone, set aRate to 1.
1.4753 +
1.4754 +@param aKernel ETrue, if checking is being done for the kernel heap;
1.4755 + EFalse, if checking is being done for the current thread's
1.4756 + default heap.
1.4757 +@param aType An enumeration which indicates how to simulate heap
1.4758 + allocation failure.
1.4759 +@param aRate The rate of failure; when aType is RAllocator::EDeterministic,
1.4760 + heap allocation fails every aRate attempts.
1.4761 +*/
1.4762 + {
1.4763 +
1.4764 + if (aKernel)
1.4765 + Exec::KernelHeapDebug(EDbgSetAllocFail,aType,(TAny*)aRate);
1.4766 + else
1.4767 + GetHeap()->__DbgSetAllocFail(aType,aRate);
1.4768 + }
1.4769 +
1.4770 +/**
1.4771 +Simulates a heap allocation failure for the current thread's default heap,
1.4772 +or the kernel heap.
1.4773 +
1.4774 +The aBurst failures will occur after subsequent calls to new or any of the
1.4775 +functions which allocate memory from the heap.
1.4776 +
1.4777 +The timing of the allocation failures will depend on the type of allocation failure
1.4778 +requested, i.e. on the value of aType.
1.4779 +
1.4780 +The simulation of heap allocation failure is cancelled if aType is given
1.4781 +the value RAllocator::ENone.
1.4782 +
1.4783 +
1.4784 +@param aKernel ETrue, if checking is being done for the kernel heap;
1.4785 + EFalse, if checking is being done for the current thread's
1.4786 + default heap.
1.4787 +@param aType An enumeration which indicates how to simulate heap
1.4788 + allocation failure.
1.4789 +@param aRate The rate of failure; when aType is RAllocator::EDeterministic,
1.4790 + heap allocation fails every aRate attempts.
1.4791 +@param aBurst The number of consecutive allocations that should fail.
1.4792 +
1.4793 +*/
1.4794 +EXPORT_C void User::__DbgSetBurstAllocFail(TBool aKernel, RAllocator::TAllocFail aType, TUint aRate, TUint aBurst)
1.4795 + {
1.4796 + if (aKernel)
1.4797 + {
1.4798 + SRAllocatorBurstFail burstFail;
1.4799 + burstFail.iRate = aRate;
1.4800 + burstFail.iBurst = aBurst;
1.4801 + Exec::KernelHeapDebug(EDbgSetBurstAllocFail, aType, (TAny*)&burstFail);
1.4802 + }
1.4803 + else
1.4804 + GetHeap()->__DbgSetBurstAllocFail(aType, aRate, aBurst);
1.4805 + }
1.4806 +
1.4807 +
1.4808 +/**
1.4809 +Returns the number of heap allocation failures the current debug allocator fail
1.4810 +function has caused so far.
1.4811 +
1.4812 +This is intended to only be used with fail types RAllocator::EFailNext,
1.4813 +RAllocator::EBurstFailNext, RAllocator::EDeterministic and
1.4814 +RAllocator::EBurstDeterministic. The return value is unreliable for
1.4815 +all other fail types.
1.4816 +
1.4817 +@return The number of heap allocation failures the current debug fail
1.4818 +function has caused.
1.4819 +
1.4820 +@see RAllocator::TAllocFail
1.4821 +*/
1.4822 +EXPORT_C TUint User::__DbgCheckFailure(TBool aKernel)
1.4823 + {
1.4824 + TUint r;
1.4825 + if (aKernel)
1.4826 + Exec::KernelHeapDebug(EDbgCheckFailure, 0, (TAny*)&r);
1.4827 + else
1.4828 + r = GetHeap()->__DbgCheckFailure();
1.4829 + return r;
1.4830 + }
1.4831 +
1.4832 +EXPORT_C TInt RProcess::Create(const TDesC &aFileName,const TDesC &aCommand,TOwnerType aType)
1.4833 +/**
1.4834 +Starts a new process, loading the specified executable.
1.4835 +
1.4836 +The executable can be in ROM or RAM.
1.4837 +
1.4838 +By default, ownership of this process handle is vested in the current process,
1.4839 +but can be vested in the current thread by specifying EOwnerThread as the
1.4840 +third parameter to this function.
1.4841 +
1.4842 +@param aFileName A descriptor containing the full path name of the executable
1.4843 + to be loaded. If this name has no file extension,
1.4844 + an extension of .EXE is appended. The length of the resulting
1.4845 + full path name must not be greater than KMaxFileName.
1.4846 + The length of the file name itself must not be greater
1.4847 + than KMaxProcessName. If no path is specified, the system will
1.4848 + look in \\sys\\bin on all drives.
1.4849 +@param aCommand A descriptor containing data passed as an argument to
1.4850 + the thread function of the new process's main thread,
1.4851 + when it is first scheduled.
1.4852 +@param aType Defines the ownership of this process handle. If not
1.4853 + specified, EOwnerProcess is the default.
1.4854 +
1.4855 +@return KErrNone if successful, otherwise one of the other system-wide error codes.
1.4856 +*/
1.4857 + {
1.4858 +
1.4859 + return Create(aFileName, aCommand, TUidType(), aType);
1.4860 + }
1.4861 +
1.4862 +
1.4863 +
1.4864 +
1.4865 +EXPORT_C TInt RProcess::Create(const TDesC &aFileName,const TDesC &aCommand,const TUidType &aUidType, TOwnerType aType)
1.4866 +/**
1.4867 +Starts a new process, loading the specified executable which matches
1.4868 +the specified UID type.
1.4869 +
1.4870 +The executable can be in ROM or RAM.
1.4871 +
1.4872 +By default, ownership of this process handle is vested in the current process,
1.4873 +but can be vested in the current thread by specifying EOwnerThread as the
1.4874 +fourth parameter.
1.4875 +
1.4876 +@param aFileName A descriptor containing the full path name of the executable
1.4877 + to be loaded. If this name has no file extension,
1.4878 + an extension of .EXE is appended. The length of the resulting
1.4879 + full path name must not be greater than KMaxFileName.
1.4880 + The length of the file name itself must not be greater
1.4881 + than KMaxProcessName. If no path is specified, the system will
1.4882 + look in \\sys\\bin on all drives.
1.4883 +@param aCommand A descriptor containing data passed as an argument to
1.4884 + the thread function of the new process's main thread,
1.4885 + when it is first scheduled.
1.4886 +@param aUidType A UID type (a triplet of UIDs) which the executable must match.
1.4887 +@param aType Defines the ownership of this process handle. If not specified,
1.4888 + EOwnerProcess is the default.
1.4889 +
1.4890 +@return KErrNone if successful, otherwise one of the other system-wide error
1.4891 + codes.
1.4892 +*/
1.4893 + {
1.4894 +
1.4895 + RLoader loader;
1.4896 + TInt r=loader.Connect();
1.4897 + if (r==KErrNone)
1.4898 + r=loader.LoadProcess(iHandle,aFileName,aCommand,aUidType,aType);
1.4899 + loader.Close();
1.4900 + return r;
1.4901 + }
1.4902 +
1.4903 +
1.4904 +EXPORT_C TInt RProcess::CreateWithStackOverride(const TDesC& aFileName,const TDesC& aCommand, const TUidType &aUidType, TInt aMinStackSize, TOwnerType aType)
1.4905 +/**
1.4906 +Starts a new process, loading the specified executable which matches
1.4907 +the specified UID type and the minimum stack size is the specified value.
1.4908 +
1.4909 +The executable can be in ROM or RAM.
1.4910 +
1.4911 +By default, ownership of this process handle is vested in the current process,
1.4912 +but can be vested in the current thread by specifying EOwnerThread as the
1.4913 +fourth parameter.
1.4914 +
1.4915 +
1.4916 +@param aFileName A descriptor containing the full path name of the executable
1.4917 + to be loaded. If this name has no file extension,
1.4918 + an extension of .EXE is appended. The length of the resulting
1.4919 + full path name must not be greater than KMaxFileName.
1.4920 + The length of the file name itself must not be greater
1.4921 + than KMaxProcessName. If no path is specified, the system will
1.4922 + look in \\sys\\bin on all drives.
1.4923 +@param aCommand A descriptor containing data passed as an argument to
1.4924 + the thread function of the new process's main thread,
1.4925 + when it is first scheduled.
1.4926 +@param aUidType A UID type (a triplet of UIDs) which the executable must match.
1.4927 +@param aMinStackSize Minimum stack size of the new process. If this is less than
1.4928 + than the stack size set in the image header of the executable,
1.4929 + the minimum stack size will be set to the image header stack
1.4930 + size.
1.4931 +@param aType Defines the ownership of this process handle. If not specified,
1.4932 + EOwnerProcess is the default.
1.4933 +
1.4934 +@return KErrNone if successful, otherwise one of the other system-wide error
1.4935 + codes.
1.4936 +*/
1.4937 + {
1.4938 +
1.4939 + RLoader loader;
1.4940 + TInt r=loader.Connect();
1.4941 + if (r==KErrNone)
1.4942 + {
1.4943 + r=loader.LoadProcess(iHandle,aFileName,aCommand,aUidType,aMinStackSize,aType);
1.4944 + }
1.4945 + loader.Close();
1.4946 + return r;
1.4947 + }
1.4948 +
1.4949 +
1.4950 +
1.4951 +EXPORT_C TInt User::LoadLogicalDevice(const TDesC &aFileName)
1.4952 +/**
1.4953 +Loads the logical device driver (LDD) DLL with the specified filename.
1.4954 +
1.4955 +The function searches the system path for the LDD DLL, and loads it. It then
1.4956 +makes a kernel server call that:
1.4957 +
1.4958 +1. creates the LDD factory object, an instance of a DLogicalDevice derived
1.4959 + class; this involves checking the first UID value to make sure that the DLL
1.4960 + is a valid LDD before proceeding to call the exported function at
1.4961 + ordinal 1, which creates the LDD factory object on the kernel heap
1.4962 +
1.4963 +2. calls the LDD factory object's Install() function to complete the installation
1.4964 +
1.4965 +3. adds the new LDD factory object to the kernel's list of LDD factory objects.
1.4966 +
1.4967 +@param aFileName A reference to the descriptor containing the name of the
1.4968 + physical device driver DLL. If the filename has no extension,
1.4969 + .LDD is assumed by default.
1.4970 +
1.4971 +@return KErrNone if successful or one of the system-wide error codes.
1.4972 +*/
1.4973 + {
1.4974 + RLoader loader;
1.4975 + return loader.LoadDeviceDriver(aFileName, 0);
1.4976 + }
1.4977 +
1.4978 +
1.4979 +
1.4980 +
1.4981 +EXPORT_C TInt User::FreeLogicalDevice(const TDesC &aDeviceName)
1.4982 +/**
1.4983 +Frees the logical device driver DLL associated with a specified driver name.
1.4984 +
1.4985 +@param aDeviceName The name of the logical device driver object. This must
1.4986 + match the name set during installation of the logical
1.4987 + device. Typically, this is done in an implementation
1.4988 + of DLogicalDevice::Install() through a call to SetName().
1.4989 + Note that the name is rarely the same as the device's
1.4990 + filename. The name of a logical device driver object
1.4991 + can be discovered by using TFindLogicalDevice.
1.4992 +
1.4993 +@return KErrNone if successful or one of the system-wide error codes. KErrNone
1.4994 + will be returned if the device is not found as it may have already been
1.4995 + freed.
1.4996 +*/
1.4997 + {
1.4998 + TBuf8<KMaxFullName> aDeviceName8;
1.4999 + aDeviceName8.Copy(aDeviceName);
1.5000 + return Exec::DeviceFree(aDeviceName8,0);
1.5001 + }
1.5002 +
1.5003 +
1.5004 +
1.5005 +
1.5006 +EXPORT_C TInt User::LoadPhysicalDevice(const TDesC &aFileName)
1.5007 +/**
1.5008 +Loads the physical device driver (PDD) DLL with the specified filename.
1.5009 +
1.5010 +The function searches the system path for the PDD DLL, and loads it. It then
1.5011 +makes a kernel server call that:
1.5012 +
1.5013 +1. creates the PDD factory object, an instance of a DPhysicalDevice derived class;
1.5014 + this involves checking the first UID value to make sure that the DLL is a
1.5015 + valid PDD before proceeding to call the exported function at ordinal 1, which
1.5016 + creates the PDD factory object on the kernel heap
1.5017 +
1.5018 +2. calls the PDD factory object's Install() function to complete the installation
1.5019 +
1.5020 +2. adds the new PDD factory object to the kernel's list of PDD factory objects.
1.5021 +
1.5022 +@param aFileName A reference to the descriptor containing the name of the
1.5023 + physical device driver DLL. If the filename has no extension,
1.5024 + .PDD is assumed by default.
1.5025 +
1.5026 +@return KErrNone if successful or one of the system-wide error codes.
1.5027 +*/
1.5028 + {
1.5029 + RLoader loader;
1.5030 + return loader.LoadDeviceDriver(aFileName, 1);
1.5031 + }
1.5032 +
1.5033 +
1.5034 +
1.5035 +
1.5036 +/**
1.5037 +Frees the physical device driver DLL associated with a specified driver name.
1.5038 +
1.5039 +@param aDeviceName The name of the physical device driver object. This must
1.5040 + match the name set during installation of the physical
1.5041 + device. Typically, this is done in an implementation of
1.5042 + DPhysicalDevice::Install() through a call to SetName().
1.5043 + Note that the name is rarely the same as the device's
1.5044 + filename. The name of a physical device driver object can
1.5045 + be discovered by using TFindPhysicalDevice.
1.5046 +
1.5047 +@return KErrNone if successful or one of the system-wide error codes. KErrNone
1.5048 + will be returned if the device is not found as it may have already
1.5049 + been freed.
1.5050 +*/
1.5051 +EXPORT_C TInt User::FreePhysicalDevice(const TDesC &aDeviceName)
1.5052 +
1.5053 + {
1.5054 + TBuf8<KMaxFullName> aDeviceName8;
1.5055 + aDeviceName8.Copy(aDeviceName);
1.5056 + return Exec::DeviceFree(aDeviceName8,1);
1.5057 + }
1.5058 +
1.5059 +
1.5060 +
1.5061 +
1.5062 +EXPORT_C TInt RLoader::Connect()
1.5063 +//
1.5064 +// Connect with the loader.
1.5065 +//
1.5066 + {
1.5067 + _LIT(KLoaderServerName,"!Loader");
1.5068 + return CreateSession(KLoaderServerName,Version(),0);
1.5069 + }
1.5070 +
1.5071 +TVersion RLoader::Version() const
1.5072 +//
1.5073 +// Return the client side version number.
1.5074 +//
1.5075 + {
1.5076 +
1.5077 + return TVersion(KLoaderMajorVersionNumber,KLoaderMinorVersionNumber,KE32BuildVersionNumber);
1.5078 + }
1.5079 +
1.5080 +TInt RLoader::LoadProcess(TInt& aHandle, const TDesC& aFileName, const TDesC& aCommand, const TUidType& aUidType, TOwnerType aType)
1.5081 +//
1.5082 +// Execute another process.
1.5083 +//
1.5084 + {
1.5085 +
1.5086 + return (LoadProcess(aHandle, aFileName, aCommand, aUidType, KDefaultStackSize, aType));
1.5087 +
1.5088 + }
1.5089 +
1.5090 +
1.5091 +/**
1.5092 + Execute another process.
1.5093 +
1.5094 + @param aHandle
1.5095 + @param aFileName
1.5096 + @param aCommand
1.5097 + @param aUidType
1.5098 + @param aMinStackSize
1.5099 + @param aType
1.5100 +
1.5101 + @return
1.5102 + KErrNone if process created
1.5103 + KErrBadName if aFileName.Length() > KMaxFileName
1.5104 + KErrArgument if aMinStackSize < 0
1.5105 +
1.5106 +*/
1.5107 +TInt RLoader::LoadProcess(TInt& aHandle, const TDesC& aFileName, const TDesC& aCommand, const TUidType& aUidType, TInt aMinStackSize, TOwnerType aType)
1.5108 + {
1.5109 +
1.5110 + __IF_DEBUG(Print(_L("RLoader::LoadProcess started with %d bytes stack.\n"), aMinStackSize));
1.5111 +
1.5112 + if( 0 > aMinStackSize )
1.5113 + return KErrArgument;
1.5114 +
1.5115 + TLdrInfo info;
1.5116 + info.iRequestedUids=aUidType; // match these uids only
1.5117 + info.iOwnerType=aType;
1.5118 +
1.5119 + info.iMinStackSize=aMinStackSize;
1.5120 +
1.5121 + if (aFileName.Length()>KMaxFileName)
1.5122 + return KErrBadName;
1.5123 +
1.5124 + TPckg<TLdrInfo> infoBuf(info);
1.5125 +
1.5126 + TInt r = SendReceive(ELoadProcess, TIpcArgs((TDes8*)&infoBuf, (const TDesC*)&aFileName, (const TDesC*)&aCommand) );
1.5127 + aHandle = info.iHandle;
1.5128 + __IF_DEBUG(Print(_L("LoadProcess returning %d"),r));
1.5129 + return r;
1.5130 + }
1.5131 +
1.5132 +/**
1.5133 + Check if the hash for the given library exists and optionally validate it.
1.5134 +
1.5135 + @param aFileName the same as for RLoader::LoadLibrary
1.5136 + @param aValidateHash if ETrue this function will validate library hash if it exists. Requires fully specified aFileName.
1.5137 +
1.5138 + @return
1.5139 + KErrNotSupported this feature is not supported by the emulator
1.5140 + KErrNone if aValidateHash=EFalse, it means that the hash exists; if aValidateHash=ETrue, hash exists and valid,
1.5141 + KErrCorrupt if aValidateHash=ETrue, the library hash exists but NOT valid,
1.5142 + KErrNotFound no hash found
1.5143 + KErrArgument bad file name
1.5144 +
1.5145 +*/
1.5146 +EXPORT_C TInt RLoader::CheckLibraryHash(const TDesC& aFileName, TBool aValidateHash/*=EFalse*/)
1.5147 + {
1.5148 + __IF_DEBUG(Print(_L("RLoader::CheckLibraryHash")));
1.5149 +
1.5150 + TLdrInfo info;
1.5151 + TPckg<TLdrInfo> infoBuf(info);
1.5152 + info.iOwnerType=EOwnerThread;
1.5153 +
1.5154 + TInt r = SendReceive(ECheckLibraryHash, TIpcArgs((TDes8*)&infoBuf, (const TDesC*)&aFileName, aValidateHash) );
1.5155 +
1.5156 + return r;
1.5157 + }
1.5158 +
1.5159 +EXPORT_C TInt RLoader::LoadLibrary(TInt& aHandle, const TDesC& aFileName, const TDesC& aPath, const TUidType& aUidType, TUint32 aModuleVersion)
1.5160 +//
1.5161 +// Load a DLL
1.5162 +//
1.5163 + {
1.5164 +
1.5165 + __IF_DEBUG(Print(_L("RLoader::LoadLibrary")));
1.5166 + TLdrInfo info;
1.5167 + TPckg<TLdrInfo> infoBuf(info);
1.5168 + info.iRequestedUids=aUidType; // match these uids only
1.5169 + info.iOwnerType=EOwnerThread;
1.5170 + info.iRequestedVersion=aModuleVersion;
1.5171 + if (aFileName.Length()>KMaxFileName)
1.5172 + return KErrBadName;
1.5173 + aHandle=0;
1.5174 +
1.5175 + TInt r=E32Loader::WaitDllLock();
1.5176 + if (r==KErrNone)
1.5177 + {
1.5178 + r = SendReceive(ELoadLibrary, TIpcArgs((TDes8*)&infoBuf, (const TDesC*)&aFileName, (const TDesC*)&aPath) );
1.5179 + aHandle=info.iHandle;
1.5180 + if (r!=KErrNone)
1.5181 + E32Loader::ReleaseDllLock();
1.5182 + }
1.5183 + __IF_DEBUG(Print(_L("LoadLibrary returning %d"),r));
1.5184 + return r;
1.5185 + }
1.5186 +
1.5187 +
1.5188 +EXPORT_C TInt RLoader::GetInfo(const TDesC& aFileName, TDes8& aInfoBuf)
1.5189 +//
1.5190 +// Get capabilities of a DLL
1.5191 +//
1.5192 + {
1.5193 + __IF_DEBUG(Print(_L("RLoader::GetInfo")));
1.5194 + TLdrInfo info;
1.5195 + TPckg<TLdrInfo> infoBuf(info);
1.5196 + info.iOwnerType=EOwnerThread;
1.5197 + if (aFileName.Length()>KMaxFileName)
1.5198 + return KErrBadName;
1.5199 + TInt r = SendReceive(EGetInfo, TIpcArgs((TDes8*)&infoBuf, (const TDesC*)&aFileName, (TDes8*)&aInfoBuf) );
1.5200 + __IF_DEBUG(Print(_L("GetInfo returning %d"),r));
1.5201 + return r;
1.5202 + }
1.5203 +
1.5204 +
1.5205 +EXPORT_C TInt RLoader::Delete(const TDesC& aFileName)
1.5206 +/**
1.5207 + Ask the loader to delete a file. This function should be used instead
1.5208 + of RFs::Delete where the supplied file may be a paged executable, although
1.5209 + it can be used for any file. A file that is currently paged may be moved
1.5210 + by the system, and deleted later, when the file is no longer needed. This means
1.5211 + that using this function may not immediately release the disk space associated
1.5212 + with the file.
1.5213 +
1.5214 + @param aFileName Fully-qualified filename.
1.5215 + @return Symbian OS error code. Additionally, KErrBadName is
1.5216 + returned if the supplied filename is not fully qualified..
1.5217 + @capability Tcb
1.5218 + @capability AllFiles
1.5219 + */
1.5220 + {
1.5221 + __IF_DEBUG(Printf(">RLoader::Delete,%S", &aFileName));
1.5222 + TInt r = SendReceive(ELdrDelete, TIpcArgs(0, &aFileName));
1.5223 + __IF_DEBUG(Printf("<RLoader::Delete,%d", r));
1.5224 + return r;
1.5225 + }
1.5226 +
1.5227 +#ifdef __WINS__
1.5228 +
1.5229 +#include <emulator.h>
1.5230 +
1.5231 +TInt RLoader::GetInfoFromHeader(const TDesC8& aHeader, TDes8& aInfoBuf)
1.5232 + {
1.5233 + __IF_DEBUG(Print(_L("RLoader::GetInfoFromHeader")));
1.5234 +
1.5235 + TInt r = KErrNone;
1.5236 +
1.5237 + Emulator::TModule module;
1.5238 + module.iBase = aHeader.Ptr();
1.5239 + TProcessCreateInfo info;
1.5240 + module.GetInfo(info);
1.5241 +
1.5242 + RLibrary::TInfoV2 ret_info;
1.5243 + memclr(&ret_info,sizeof(ret_info));
1.5244 + ret_info.iModuleVersion = info.iModuleVersion;
1.5245 + ret_info.iUids = info.iUids;
1.5246 + *(SSecurityInfo*)&ret_info.iSecurityInfo = info.iS;
1.5247 + ret_info.iHardwareFloatingPoint = EFpTypeNone;
1.5248 + TPckg<RLibrary::TInfoV2> ret_pckg(ret_info);
1.5249 + if (aInfoBuf.MaxLength() < ret_pckg.Length())
1.5250 + ret_pckg.SetLength(aInfoBuf.MaxLength());
1.5251 + aInfoBuf=ret_pckg;
1.5252 +
1.5253 + __IF_DEBUG(Print(_L("GetInfoFromHeader returning %d"),r));
1.5254 + return r;
1.5255 + }
1.5256 +
1.5257 +#else // not __WINS__ ...
1.5258 +
1.5259 +TInt RLoader::GetInfoFromHeader(const TDesC8& aHeader, TDes8& aInfoBuf)
1.5260 + {
1.5261 + __IF_DEBUG(Print(_L("RLoader::GetInfoFromHeader")));
1.5262 + TInt r = SendReceive(EGetInfoFromHeader, TIpcArgs(&aHeader, &aInfoBuf) );
1.5263 + __IF_DEBUG(Print(_L("GetInfoFromHeader returning %d"),r));
1.5264 + return r;
1.5265 + }
1.5266 +
1.5267 +#endif // __WINS__
1.5268 +
1.5269 +TInt RLoader::LoadDeviceDriver(const TDesC& aFileName, TInt aDeviceType)
1.5270 + {
1.5271 + TInt r=Connect();
1.5272 + if (r==KErrNone)
1.5273 + {
1.5274 + TInt m = aDeviceType ? ELoadPhysicalDevice : ELoadLogicalDevice;
1.5275 + r = SendReceive(m, TIpcArgs(0, (const TDesC*)&aFileName, 0) );
1.5276 + Close();
1.5277 + }
1.5278 + return r;
1.5279 + }
1.5280 +
1.5281 +TInt RLoader::LoadLocale(const TDesC& aLocaleDllName, TLibraryFunction* aExportList)
1.5282 + {
1.5283 + TInt r=Connect();
1.5284 + if (r==KErrNone)
1.5285 + {
1.5286 + TInt size = KNumLocaleExports * sizeof(TLibraryFunction);
1.5287 + TPtr8 functionListBuf((TUint8*)aExportList, size, size);
1.5288 + r = SendReceive(ELoadLocale, TIpcArgs(0, (const TDesC*)&aLocaleDllName, &functionListBuf) );
1.5289 + Close();
1.5290 + }
1.5291 + return r;
1.5292 + }
1.5293 +
1.5294 +EXPORT_C TInt RLoader::DebugFunction(TInt aFunction, TInt a1, TInt a2, TInt a3)
1.5295 + {
1.5296 + return SendReceive(ELoaderDebugFunction, TIpcArgs(aFunction, a1, a2, a3) );
1.5297 + }
1.5298 +
1.5299 +EXPORT_C TInt RLoader::CancelLazyDllUnload()
1.5300 + {
1.5301 + return SendReceive(ELoaderCancelLazyDllUnload, TIpcArgs() );
1.5302 + }
1.5303 +
1.5304 +#ifdef __USERSIDE_THREAD_DATA__
1.5305 +
1.5306 +EXPORT_C TInt UserSvr::DllSetTls(TInt aHandle, TAny* aPtr)
1.5307 +//
1.5308 +// Set the value of the Thread Local Storage variable.
1.5309 +//
1.5310 + {
1.5311 + return LocalThreadData()->DllSetTls(aHandle, KDllUid_Default, aPtr);
1.5312 + }
1.5313 +
1.5314 +EXPORT_C TInt UserSvr::DllSetTls(TInt aHandle, TInt aDllUid, TAny* aPtr)
1.5315 +//
1.5316 +// Set the value of the Thread Local Storage variable.
1.5317 +//
1.5318 + {
1.5319 + return LocalThreadData()->DllSetTls(aHandle, aDllUid, aPtr);
1.5320 + }
1.5321 +
1.5322 +EXPORT_C void UserSvr::DllFreeTls(TInt aHandle)
1.5323 +//
1.5324 +// Remove the Thread Local Storage variable.
1.5325 +//
1.5326 + {
1.5327 + return LocalThreadData()->DllFreeTls(aHandle);
1.5328 + }
1.5329 +
1.5330 +#else
1.5331 +
1.5332 +EXPORT_C TInt UserSvr::DllSetTls(TInt aHandle, TAny* aPtr)
1.5333 +//
1.5334 +// Set the value of the Thread Local Storage variable.
1.5335 +//
1.5336 + {
1.5337 + return Exec::DllSetTls(aHandle, KDllUid_Default, aPtr);
1.5338 + }
1.5339 +
1.5340 +EXPORT_C TInt UserSvr::DllSetTls(TInt aHandle, TInt aDllUid, TAny* aPtr)
1.5341 +//
1.5342 +// Set the value of the Thread Local Storage variable.
1.5343 +//
1.5344 + {
1.5345 + return Exec::DllSetTls(aHandle, aDllUid, aPtr);
1.5346 + }
1.5347 +
1.5348 +EXPORT_C void UserSvr::DllFreeTls(TInt aHandle)
1.5349 +//
1.5350 +// Remove the Thread Local Storage variable.
1.5351 +//
1.5352 + {
1.5353 + Exec::DllFreeTls(aHandle);
1.5354 + }
1.5355 +
1.5356 +#endif
1.5357 +
1.5358 +
1.5359 +
1.5360 +
1.5361 +EXPORT_C TInt RChangeNotifier::Create()
1.5362 +/**
1.5363 +Creates a change notifier, and opens this handle to that change notifier.
1.5364 +
1.5365 +Ownership of this change notifier is vested in the current process.
1.5366 +
1.5367 +@return KErrNone if successful, otherwise one of the other system-wide error codes.
1.5368 +*/
1.5369 + {
1.5370 + return SetReturnedHandle(Exec::ChangeNotifierCreate(EOwnerProcess),*this);
1.5371 + }
1.5372 +
1.5373 +
1.5374 +
1.5375 +
1.5376 +EXPORT_C TInt RUndertaker::Create()
1.5377 +/**
1.5378 +Creates a thread-death notifier, and opens this handle to
1.5379 +that thread-death notifier.
1.5380 +
1.5381 +Ownership of this thread-death notifier is vested in the current process.
1.5382 +
1.5383 +@return KErrNone, if successful; otherwise one of
1.5384 + the other system-wide error codes.
1.5385 +*/
1.5386 + {
1.5387 + return SetReturnedHandle(Exec::UndertakerCreate(EOwnerProcess),*this);
1.5388 + }
1.5389 +
1.5390 +
1.5391 +
1.5392 +
1.5393 +EXPORT_C TInt RUndertaker::Logon(TRequestStatus& aStatus, TInt& aThreadHandle) const
1.5394 +/**
1.5395 +Issues a request for notification of the death of a thread.
1.5396 +
1.5397 +When another thread dies, the request completes and the TRequestStatus object
1.5398 +contains the value KErrDied; in addition, aThreadHandle contains
1.5399 +the handle-number of the dying thread.
1.5400 +
1.5401 +The requesting thread can construct a proper handle for the dying thread
1.5402 +using the code:
1.5403 +
1.5404 +@code
1.5405 +{
1.5406 +RThread r;
1.5407 +r.SetHandle(aThreadHandle);
1.5408 +...r.Close();
1.5409 +}
1.5410 +@endcode
1.5411 +
1.5412 +Alternatively, if an outstanding request is cancelled by a call
1.5413 +to LogonCancel(), then the request completes with the value KErrCancel.
1.5414 +
1.5415 +Note that if a request completes normally, i.e. not as a result of
1.5416 +a LogonCancel(), then the handle to the dying thread must be closed
1.5417 +when there is no further interest in it.
1.5418 +
1.5419 +@param aStatus A reference to the request status object.
1.5420 +@param aThreadHandle The handle-number representing the dying thread.
1.5421 +
1.5422 +@return KErrInUse if there is an outstanding request; KErrNone otherwise.
1.5423 +
1.5424 +@see RUndertaker::LogonCancel()
1.5425 +*/
1.5426 + {
1.5427 + aStatus=KRequestPending;
1.5428 + return Exec::UndertakerLogon(iHandle,aStatus,aThreadHandle);
1.5429 + }
1.5430 +
1.5431 +
1.5432 +
1.5433 +
1.5434 +EXPORT_C TInt RUndertaker::LogonCancel() const
1.5435 +/**
1.5436 +Cancels an outstanding notification request to the thread-death notifier.
1.5437 +
1.5438 +@return KErrGeneral, if there is no outstanding notification request; KErrNone otherwise.
1.5439 +
1.5440 +@see RUndertaker::Logon()
1.5441 +*/
1.5442 + {
1.5443 + return Exec::UndertakerLogonCancel(iHandle);
1.5444 + }
1.5445 +
1.5446 +
1.5447 +
1.5448 +
1.5449 +/**
1.5450 +Sets the machine configuration.
1.5451 +
1.5452 +@param aConfig Descriptor containing the machine configuration data
1.5453 +
1.5454 +@return KErrNone, if sucessful, otherwise one of the other system-wide
1.5455 + error codes.
1.5456 +
1.5457 +@capability WriteDeviceData
1.5458 +*/
1.5459 +EXPORT_C TInt User::SetMachineConfiguration(const TDesC8& aConfig)
1.5460 + {
1.5461 + return Exec::SetMachineConfiguration(aConfig);
1.5462 + }
1.5463 +
1.5464 +
1.5465 +
1.5466 +
1.5467 +EXPORT_C TInt User::CompressAllHeaps()
1.5468 +/**
1.5469 +Compresses all the chunks containing heaps.
1.5470 +
1.5471 +@deprecated This function is no longer supported, and calling it has no effect.
1.5472 +
1.5473 +@return KErrNone
1.5474 +*/
1.5475 + {
1.5476 +
1.5477 + return KErrNone; // don't do this any more
1.5478 + }
1.5479 +
1.5480 +
1.5481 +
1.5482 +
1.5483 +EXPORT_C TInt UserSvr::ChangeLocale(const TDesC& aLocaleDllName)
1.5484 + {
1.5485 + if(aLocaleDllName.Length() == 0)
1.5486 + {
1.5487 + //support reverting to defaults
1.5488 + TInt r = UserSvr::LocalePropertiesSetDefaults();
1.5489 + if(r == KErrNone)
1.5490 + Exec::SetUTCTimeAndOffset(0,0,ETimeSetOffset,EChangesLocale);
1.5491 + return r;
1.5492 + }
1.5493 + TExtendedLocale locale;
1.5494 + TInt r = locale.LoadLocale(aLocaleDllName);
1.5495 + if(r == KErrNone)
1.5496 + {
1.5497 + r = locale.SaveSystemSettings();
1.5498 + }
1.5499 + return r;
1.5500 + }
1.5501 +
1.5502 +EXPORT_C TInt UserSvr::ResetMachine(TMachineStartupType aType)
1.5503 +//
1.5504 +// Reset the machine. Currently only aType==EStartupWarmReset is supported.
1.5505 +//
1.5506 + {
1.5507 +
1.5508 + return Exec::ResetMachine(aType);
1.5509 + }
1.5510 +