Class RChunk

RChunk

Support

Supported from 5.0

Description

Provides a handle to a chunk. The chunk itself is a Kernel object.

Derivation

RChunk Provides a handle to a chunk RHandleBase Handle to an object

Defined in RChunk:
Adjust(), AdjustDoubleEnded(), Base(), Bottom(), CreateDoubleEndedGlobal(), CreateDoubleEndedLocal(), CreateGlobal(), CreateLocal(), IsReadable(), IsWritable(), MaxSize(), Open(), OpenGlobal(), Read(), ReserveAt(), Size(), Top(), Write()

Inherited from RHandleBase:
Close(), Duplicate(), Handle(), SetHandle()

TInt CreateLocal(TInt aSize,TInt aMaxSize,TOwnerType aType=EOwnerProcess);

Description

Creates a local chunk. The chunk is local to the process creating it; i.e. it is private to the process creating it and is not intended for access by other user processes.

aMaxSize specifies the maximum size of the chunk and aSize specifies the number of bytes to be committed on creation of the chunk. Both values are rounded up to the next nearest processor page boundary value if they are not already on a processor page boundary.

The committed region always starts at the bottom of the reserved region.

By default, ownership of this chunk handle is vested in the current process. Ownership of the chunk handle can be vested in the current thread by passing EOwnerThread as the third parameter to this function.

Parameters

TInt aSize The number of bytes committed to this chunk. The value must not be negative, otherwise the function raises a USER 100 panic. The value must be less than the supplied value of aMaxSize, otherwise the function raises a USER 101 panic. TInt aMaxSize The maximum size to which the reserved region of this chunk can grow. The value must not be negative, otherwise the function raises a USER 99 panic. The value must be greater than or equal to the supplied value of aSize, otherwise the function raises a USER 101 panic. TOwnerType aType An enumeration whose enumerators define the ownership of this chunk handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt CreateGlobal(const TDesC& aName,TInt aSize,TInt aMaxSize,TOwnerType aType=EOwnerProcess);

Description

Creates a global chunk. The chunk is global; i.e. it is visible to all processes and is intended for access by other user processes.

aMaxSize specifies the maximum size of the chunk and aSize specifies the number of bytes to be committed on creation of the chunk. Both values are rounded up to the next nearest processor page boundary value ,if they are not already on a processor page boundary value.

The committed region always starts at the bottom of the reserved region.

The descriptor aName contains the name to be assigned to this global chunk.

By default, ownership of this chunk handle is vested in the current process. Ownership of the chunk handle can be vested in the current thread by passing EOwnerThread as the third parameter to this function.

Parameters

const TDesC& aName A reference to a descriptor containing the name to be assigned to this global chunk. The length of the descriptor must be no greater than that allowed for a TName type. TInt aSize The number of bytes committed to this chunk. The value must must not be negative, otherwise the function raises a USER 100 panic. The value must be less than the supplied value of aMaxSize, otherwise the function raises a USER 101 panic. TInt aMaxSize The maximum size to which the reserved region of this chunk can grow. The value must not be negative, otherwise the function raises a USER 99 panic. The value must be greater than or equal to the supplied value of aSize, otherwise the function raises a USER 101 panic. TOwnerType aType=EOwnerProcess An enumeration whose enumerators define the ownership of this chunk handle. If not explicitly specified, EOwnerProcess is taken as default

Return value

TInt KErrNone if successful, otherwise another of the system error codes.

TInt CreateDoubleEndedLocal(TInt aInitialBottom, TInt aInitialTop,TInt aMaxSize,TOwnerType aType=EOwnerProcess);

Description

Creates a local, double ended, chunk. The chunk is local to the process creating it; i.e. it is private to the process creating it and is not intended for access by other user processes.

The committed region of a double ended chunk can be any contiguous subset of the reserved region.

aMaxSize specifies the maximum size of the chunk.

The difference between aInitialTop and aInitialBottom gives the number of bytes to be committed, on creation of the chunk; aInitialBottom gives the offset of the bottom of the committed region from the base of the chunk's reserved region; aInitialTop gives the offset of the top of the committed region from the base of the chunk's reserved region.

Both aInitialBottom and aInitialTop are rounded up to the next nearest processor page boundary value, if they are not already on a processor page boundary value.

By default, ownership of this chunk handle is vested in the current process. Ownership of the chunk handle can be vested in the current thread by passing EOwnerThread as the third parameter to this function.

Note that:

• the lowest valid address in a double ended chunk is the sum of the base of the chunk's reserved region plus the adjusted value of aInitialBottom

  the highest valid address in a double ended chunk is the the sum of the base of the chunk's reserved region plus the adjusted value of aInitialTop - 1.

Parameters

TInt aInitialBottom The offset of the bottom of the new committed region from the base of the chunk's reserved region. The value must not be negative, otherwise the function raises a USER 120 panic. The value must be less than or equal to the supplied value aInitialTop, otherwise the function raises a USER 122 panic. TInt aInitialTop The offset of the top of the new committed region from the base of the chunk's reserved region. The value must not be negative, otherwise the function raises a USER 121 panic. The value must be greater than or equal to the supplied value of aInitialBottom, otherwise the function raises a USER 122 panic. The value must be less than or equal to the supplied value of aMaxSize, otherwise the function raises a USER 123 panic. TInt aMaxSize The maximum size to which the reserved region of this chunk can grow. The value must not be negative, otherwise the function raises a USER 99 panic. The value must be greater than or equal to the supplied value of aInitialTop, otherwise the function raises a USER 123 panic. TOwnerType aType=EOwnerProcess An enumeration whose enumerators define the ownership of this chunk handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt KErrNone if successful, otherwise another of the system error codes.

TInt CreateDoubleEndedGlobal(const TDesC& aName,TInt aInitialBottom,TInt aInitialTop,TInt aMaxSize,TOwnerType aType=EOwnerProcess);

Description

Creates a global, double ended, chunk. The chunk is global; i.e. it is visible to all processes and is intended for access by other user processes.

The committed region of a double ended chunk can be any contiguous subset of the reserved region.

aMaxSize specifies the maximum size of the chunk.

The difference between aInitialTop and aInitialBottom gives the number of bytes to be committed, on creation of the chunk; aInitialBottom gives the offset of the bottom of the committed region from the base of the chunk's reserved region; aInitialTop gives the offset of the top of the committed region from the base of the chunk's reserved region.

Both aInitialBottom and aInitialTop are rounded up to the next nearest processor page boundary value, if they are not already on a processor page boundary value.

The descriptor aName contains the name to be assigned to this global chunk.

By default, ownership of this chunk handle is vested in the current process. Ownership of the chunk handle can be vested in the current thread by passing EOwnerThread as the third parameter to this function.

Note that:

• the lowest valid address in a double ended chunk is the sum of the base of the chunk's reserved region plus the adjusted value of aInitialBottom

  the highest valid address in a double ended chunk is the the sum of the base of the chunk's reserved region plus the adjusted value of aInitialTop - 1.

Parameters

const TDesC& aName A reference to a descriptor containing the name to be assigned to this global chunk. The length of the descriptor must be no greater than that allowed for a TName type. TInt aInitialBottom The offset of the bottom of the new committed region from the base of the chunk's reserved region. The value must not be negative, otherwise the function raises a USER 120 panic. The value must be less than or equal to the supplied value aInitialTop, otherwise the function raises a USER 122 panic. TInt aInitialTop The offset of the top of the new committed region from the base of the chunk's reserved region. The value must not be negative, otherwise the function raises a USER 121 panic. The value must be greater than or equal to the supplied value of aInitialBottom, otherwise the function raises a USER 122 panic. The value must be less than or equal to the supplied value of aMaxSize, otherwise the function raises a USER 123 panic. TInt aMaxSize The maximum size to which the reserved region of this chunk can grow. The value must not be negative, otherwise the function raises a USER 99 panic. The value must be greater than or equal to the supplied value of aInitialTop, otherwise the function raises a USER 123 panic. TOwnerType aType An enumeration whose enumerators define the ownership of this chunk handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt KErrNone if successful, otherwise another of the system error codes.

TInt OpenGlobal(const TDesC& aName,TBool isReadOnly,TOwnerType aType=EOwnerProcess);

Description

Opens a handle to a specific named global chunk. Full read/write access can be allowed or access can be limited to read only.

By default, ownership of this process handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Arguments

Parameters

const TDesC& aName A reference to the descriptor containing the name of the chunk to be opened. TBool isReadOnly Defines the type of access to the chunk: Specify ETrue if access is limited to read only, otherwise specify EFalse for full read/write access. TOwnerType aType An enumeration whose enumerators define ownership of this chunk handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt KErrNone if successful, otherwise another of the system error codes.

TInt Open(const TFindChunk& aFind,TOwnerType aType=EOwnerProcess);

Description

Opens a handle to the global chunk found using a TFindChunk object.

A TFindChunk object is used to find all chunks whose full names match a specified pattern.

By default, ownership of this chunk handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

const TFindChunk& aFind A reference to the TFindChunk object used to find the chunk. TOwnerType aType An enumeration whose enumerators define the ownership of this chunk handle. If not explicitly specified, EOwnerProcess is taken as default.

Return value

TInt KErrNone if successful, otherwise another of the system error codes.

See also:

• TFindChunk

TInt Adjust(TInt aNewSize) const;

Description

Changes the number of bytes committed to the chunk. This value is always rounded up to the next nearest processor page boundary.

Parameters

TInt aNewSize The number of bytes to be committed to this chunk. The value must not be negative, otherwise the function raises a USER 102 panic.

Return value

TInt KErrNone if successful, otherwise another of the system error codes.

TInt AdjustDoubleEnded(TInt aBottom, TInt aTop) const;

Description

Changes the number of bytes and the position of this double ended chunk's committed region.

The difference between aTop and aBottom gives the new size of the committed region; aBottom gives the offset of the bottom of the committed region from the base of the chunk's reserved region.

Both aBottom and aTop are rounded up to the next nearest processor page boundary.

The function fails if this chunk is not a double ended chunk; for a standard chunk, use the Adjust() function.

Note that if the initial and final committed regions intersect, the contents of the intersection are unchanged. Other parts of the committed region have undefined contents.

Note also that:

• the lowest valid address in a double ended chunk is the sum of the base of the chunk's reserved region plus the adjusted value of aBottom

  the highest valid address in a double ended chunk is the the sum of the base of the chunk's reserved region plus the adjusted value of aTop - 1.

Parameters

TInt aBottom The offset from the base of the chunk of the bottom of the committed region. The value must not be negative, otherwise the function raises a USER 124 panic. The value must be less than or equal to the supplied value of aTop, otherwise the function raises a USER 126 panic. TInt aTop The offset from the base of the chunk of the top of the committed region. The value must not be negative, otherwise the function raises a USER 125 panic. The value must be greater than or equal to the supplied value of aBottom, otherwise the function raises a USER 126 panic.

Return value

TInt KErrNone if successful, otherwise another of the system error codes.

TInt ReserveAt(TUint8* aAddr) const;

Support

Withdrawn in 6.0

Description

Forces allocation of the reserved region of this chunk at the specified linear address.

Parameters

TUint8* aAddr The linear address for this chunk's reserved region.

Return value

TInt KErrNone if successful, otherwise another of the system error codes.

TUint8* Base() const;

Description

Returns a pointer to the base of the chunk's reserved region.

Return value

TUint8* A pointer to the base of the chunk's reserved region.

TInt Size() const;

Description

Returns the current size of this chunk's committed region to this chunk.

Return value

TInt The size of the chunk's committed region.

TInt MaxSize() const;

Description

Returns the maximum size of this chunk. This maximum size of this chunk is set when the chunk is created.

Return value

TInt The maximum size of this chunk

TInt Bottom() const;

Description

Returns the offset of the bottom of the double ended chunk's committed region from the base of the chunk's reserved region.

Note that the lowest valid address in a double ended chunk is the sum of the base of the chunk's reserved region plus the value of Bottom().

Return value

TInt The offset of the bottom of the chunk's committed region from the base of the chunk's reserved region.

TInt Top() const;

Description

Returns the offset of the top of the double ended chunk's committed region from the base of the chunk's reserved region.

Note that the highest valid address in a double ended chunk is the the sum of the base of the chunk's reserved region plus the value of Top() - 1.

Return value

TInt The offset of the top of the chunk's committed region from the base of the chunk's reserved region.

TBool IsReadable() const;

Description

Is the chunk mapped into its process address space?

Return value

TBool True, if the chunk is readable; false, otherwise.

TBool IsWritable() const;

Description

Is the chunk mapped into its process address space and writable?

Return value

TBool True, if the chunk is writable; false, otherwise.

void Read(TInt aPos,TDes8& aDes) const;

Support

Withdrawn in 6.0

Description

Reads data from the chunk into an 8 bit descriptor. The data is read from the location at offset aPos from the bottom of the chunk's committed region and copied into the descriptor aDes.

By default, the number of bytes of data read from the chunk is the size of the descriptor. However if the number of bytes of data available in the chunk's committed region is less than the size of aDes, then this smaller number of bytes is taken. The number of bytes of data available in the chunk is calculated as the difference between the size of the chunk's committed region and the value of aPos.

Notes:

• The current thread is panicked with KERN-EXEC 6 if aPos is negative.

• The current thread is panicked with KERN-EXEC 6 if aPos is greater than or equal to the current number of bytes committed to the chunk (the value returned by the Size() member function).

Parameters

TInt aPos The offset from the bottom of the chunk's committed region from where data is to be read. TDes8& aDes The target descriptor for the data read from the chunk. Use the typedef TDes& where possible.

void Read(TInt aPos,TDes16& aDes) const;

Support

Withdrawn in 6.0

Description

Reads data from the chunk into a 16 bit descriptor. The data is read from the location at offset aPos from the bottom of the chunk's committed region and copied into the descriptor aDes.

By default, the number of double-bytes of data read from the chunk is the size of the descriptor. However if the number of double-bytes of data available in the chunk's committed region is less than the size of aDes, then this smaller number of bytes is taken. The number of bytes of data available in the chunk is calculated as the difference between the size of the chunk's committed region and the value of aPos.

Notes:

• The number of bytes read is guaranteed to be an even number and, if necessary, rounded down to the next even number.

• The current thread is panicked with KERN-EXEC 6 if aPos is negative.

• The current thread is panicked with KERN-EXEC 6 if aPos is greater than or equal to the current number of bytes committed to the chunk (the value returned by the Size() member function).

Parameters

TInt aPos The offset from the bottom of the chunk's committed region from where data is to be read. TDes16& aDes The target descriptor for the data read from the chunk. Use the typedef TDes& where possible.

void Read(TInt aPos,TDes8& aDes,TInt aLength) const;

Support

Withdrawn in 6.0

Description

Reads 8 bit data from the chunk, specifying the length to which the target descriptor is to be re-sized. The data is read from the location at offset aPos from the bottom of the chunk's committed region and copied into the descriptor aDes.

By default the number of bytes of data read from the chunk is the (new) size of the descriptor. However if the number of bytes of data available in the chunk's committed region is less than the size of the descriptor, then this smaller number of bytes is taken. The number of bytes of data available in the chunk is calculated as the difference between the size of the chunk's committed region and the value of aPos.

Notes:

• The current thread is panicked with KERN-EXEC 6 if aPos is negative.

• The current thread is panicked with KERN-EXEC 6 if aPos is greater than or equal to the current number of bytes committed to the chunk (the value returned by the Size() member function).

Parameters

TInt aPos The offset from the bottom of the chunk's committed region from where data is to be read. TDes8& aDes The target descriptor for the data read from the chunk. Use the typedef TDes& where possible. TInt aLength If specified, the length of data to be read from the chunk.

void Read(TInt aPos,TDes16& aDes,TInt aLength) const;

Support

Withdrawn in 6.0

Description

Reads 16 bit data from the chunk, specifying the length to which the target descriptor is to be re-sized. The data is read from the location at offset aPos from the bottom of the chunk's committed region and copied into the descriptor aDes.

By default the number of double-bytes of data read from the chunk is the (new) size of the descriptor. However if the amount of data available in the chunk's committed region is less than the size of the descriptor, then this smaller number of bytes is taken. The number of bytes of data available in the chunk is calculated as the difference between the size of the chunk's committed region and the value of aPos.

Notes:

• The number of bytes read is guaranteed to be an even number and, if necessary, rounded down to the next even number.

• The current thread is panicked with KERN-EXEC 6 if aPos is negative.

• The current thread is panicked with KERN-EXEC 6 if aPos is greater than or equal to the current number of bytes committed to the chunk (the value returned by the Size() member function).

Parameters

TInt aPos The offset from the bottom of the chunk's committed region from where data is to be read. TDes16& aDes The target descriptor for the data read from the chunk. Use the typedef TDes& where possible. TInt aLength If specified, the length of data to be read from the chunk.

void Write(TInt aPos,const TDesC8& aDes) const;

Support

Withdrawn in 6.0

Description

Writes 8 bit data into the chunk.

The data is taken from the descriptor aDes and written into the chunk, starting at offset aPos from the bottom of the chunk's committed region. The number of bytes of data written is the size of the descriptor aDes.

Note:

• The current thread is panicked with KERN-EXEC 7 if aPos is negative.

• The current thread is panicked with KERN-EXEC 7 if aPos is greater than or equal to the current number of bytes committed to the chunk (the value returned by the Size() member function).

• The current thread is panicked with KERN-EXEC 7 if aPos plus the size of the descriptor aDes is greater than the current number of bytes committed to the chunk (the value returned by the Size() member function).

Parameters

TInt aPos The offset from the bottom of the chunk's committed region where data is to be written. const TDesC8& aDes The source descriptor for the data to be written into the chunk. Use the typedef TDes& where possible.

void Write(TInt aPos,const TDesC16& aDes) const;

Support

Withdrawn in 6.0

Description

Writes 16 bit data into the chunk.

The data is taken from the descriptor aDes and written into the chunk, starting at offset aPos from the bottom of the chunk's committed region. The number of bytes of data written is the size of the descriptor aDes.

Note:

• The current thread is panicked with KERN-EXEC 7 if aPos is negative.

• The current thread is panicked with KERN-EXEC 7 if aPos is greater than or equal to the current number of bytes committed to the chunk (the value returned by the Size() member function).

• The current thread is panicked with KERN-EXEC 7 if aPos plus the size of the descriptor aDes is greater than the current number of bytes committed to the chunk (the value returned by the Size() member function).

Parameters

TInt aPos The offset from the bottom of the chunk's committed region where data is to be written. const TDesC16& aDes The source descriptor for the data to be written into the chunk. Use the typedef TDes& where possible.