RPipe Class Reference

class RPipe : public RBusLogicalChannel

RPipe class object represent the user side handle. It is derived from RBusLogicalChannel which is the base class for handle to the kernel side device driver instance. It encapsulates both named and unnamed pipe methods.

Nested Classes and Structures

Public Member Functions
IMPORT_C TInt CancelDataAvailable ()
IMPORT_C TInt CancelSpaceAvailable ()
IMPORT_C void CancelWait ()
IMPORT_C void Close ()
IMPORT_C TInt Create ( TInt , RPipe &, RPipe &, TOwnerType , TOwnerType )
TInt Create (const TInt , TOwnerType )
IMPORT_C TInt Define (const TDesC &, TInt )
IMPORT_C TInt Define (const TDesC &, TInt , const TSecurityPolicy &)
IMPORT_C TInt Destroy (const TDesC &)
IMPORT_C void Flush ()
IMPORT_C TInt HandleType ()
IMPORT_C TInt Init ()
IMPORT_C TInt MaxSize ()
const TDesC & Name ()
IMPORT_C void NotifyDataAvailable ( TRequestStatus &)
IMPORT_C void NotifySpaceAvailable ( TInt , TRequestStatus &)
TInt Open (const RPipe &, TOwnerType )
IMPORT_C TInt Open (const TDesC &, TMode )
IMPORT_C TInt Open ( TInt , TOwnerType )
IMPORT_C TInt Open ( RMessagePtr2 , TInt , TOwnerType )
TInt PipeHandle ()
IMPORT_C TInt Read ( TDes8 &, TInt )
IMPORT_C TInt ReadBlocking ( TDes8 &, TInt )
IMPORT_C TInt Size ()
TVersion VersionRequired ()
IMPORT_C void Wait (const TDesC &, TRequestStatus &)
IMPORT_C void WaitForReader (const TDesC &, TRequestStatus &)
IMPORT_C void WaitForWriter (const TDesC &, TRequestStatus &)
IMPORT_C TInt Write (const TDesC8 &, TInt )
IMPORT_C TInt WriteBlocking (const TDesC8 &, TInt )
Private Member Functions
void ReqComplete ( TRequestStatus &, TInt )
void Wait (const TDesC &, TRequestStatus &, TInt )
Inherited Functions
RBusLogicalChannel::DoCancel(TUint)
RBusLogicalChannel::DoControl(TInt)
RBusLogicalChannel::DoControl(TInt,TAny *)
RBusLogicalChannel::DoControl(TInt,TAny *,TAny *)
RBusLogicalChannel::DoCreate(const TDesC &,const TVersion &,TInt,const TDesC *,const TDesC8 *,TOwnerType,TBool)
RBusLogicalChannel::DoRequest(TInt,TRequestStatus &)
RBusLogicalChannel::DoRequest(TInt,TRequestStatus &,TAny *)
RBusLogicalChannel::DoRequest(TInt,TRequestStatus &,TAny *,TAny *)
RBusLogicalChannel::DoSvControl(TInt)
RBusLogicalChannel::DoSvControl(TInt,TAny *)
RBusLogicalChannel::DoSvControl(TInt,TAny *,TAny *)
RHandleBase::Attributes()const
RHandleBase::BTraceId()const
RHandleBase::DoExtendedClose()
RHandleBase::Duplicate(const RThread &,TOwnerType)
RHandleBase::FullName()const
RHandleBase::FullName(TDes &)const
RHandleBase::Handle()const
RHandleBase::HandleInfo(THandleInfo *)
RHandleBase::Name()const
RHandleBase::NotifyDestruction(TRequestStatus &)
RHandleBase::Open(const TFindHandleBase &,TOwnerType)
RHandleBase::OpenByName(const TDesC &,TOwnerType,TInt)
RHandleBase::RHandleBase()
RHandleBase::RHandleBase(TInt)
RHandleBase::SetHandle(TInt)
RHandleBase::SetHandleNC(TInt)
RHandleBase::SetReturnedHandle(TInt)
RHandleBase::SetReturnedHandle(TInt,RHandleBase &)
Public Member Enumerations
enum TChannelType { EChannelUnset  = 0x0, EReadChannel  = 0x1, EWriteChannel  = 0x2 }
enum TMode { EOpenToRead , EOpenToWrite , EOpenToWriteNamedPipeButFailOnNoReaders }
enum TRequest {
EDefineNamedPipe , EOpenToReadNamedPipe , EOpenToWriteNamedPipe , EOpenToWriteButFailOnNoReaderNamedPipe , EDestroyNamedPipe , ECreateUnNamedPipe , EOpenUnNamedPipe , ERead , EWrite , ESize , EReadBlocking , EWriteBlocking , EDataAvailable , EDataAvailableCount , ESpaceAvailable , EWaitNotification , EWaitNotificationCheck , ECancelSpaceAvailable , ECancelDataAvailable , ECancelWaitNotification , EFlushPipe , EClosePipe , EGetPipeInfo
}
enum TWaitRequest { EWaitForReader , EWaitForWriter }
Inherited Enumerations
RHandleBase:TAttributes
Public Member Type Definitions
typedef TPckgBuf < TPipeInfo > TPipeInfoBuf
Private Attributes
TInt iHandleType
TInt iPipeHandle
TInt iSize
Inherited Attributes
RHandleBase::iHandle

Member Functions Documentation

CancelDataAvailable()

IMPORT_C TInt CancelDataAvailable ( )

Cancels an outstanding data available notifier request.

CancelSpaceAvailable()

IMPORT_C TInt CancelSpaceAvailable ( )

Cancels an outstanding space available notifier request.

CancelWait()

IMPORT_C void CancelWait ( )

Close()

IMPORT_C void Close ( )

Close the handle. This method exhibits different behaviour depending upon whether the pipe is named or unnamed. Named pipes are allowed to persist without any open handles. Closing the last handle on a named pipe will not destroy the kernel-side object. For an unnamed pipe, closing the last handle will destroy the kernel-side pipe object. Any unread data in the pipe will be discarded. An attempt to close an unnamed pipe will have no effect. Closing a handle will not affect the state of any other handles that may be open on the pipe.

Create(TInt, RPipe &, RPipe &, TOwnerType, TOwnerType)

IMPORT_C TInt Create ( TInt aSize,
RPipe & aReader,
RPipe & aWriter,
TOwnerType aTypeR = EOwnerProcess,
TOwnerType aTypeW = EOwnerProcess
) [static]

Support for un-named pipe

Static method to create a new, unnamed pipe. By default, any thread in the process can use the handle to access the Pipe. However, specifying EOwnerThread as the second and fourth parameter to this function, means that only the creating thread can use this handle to access the Pipe.

Parameters

TInt aSize Size of the pipe to be created, in bytes.
RPipe & aReader Handle to the read end of the pipe. If the call is successful, this handle will be opened for reading.
RPipe & aWriter Handle to the write end of the pipe. If the call is successful, this handle will be opened for writing.
TOwnerType aTypeR = EOwnerProcess
TOwnerType aTypeW = EOwnerProcess The type of the ownership of the handle to be created for the read and write

Create(const TInt, TOwnerType)

TInt Create ( const TInt sSize,
TOwnerType aType = EOwnerProcess
)

Creates a Kernel side pipe and opens a handle for reading. By default any thread in the process can use the handle to access to Read the Pipe. However, specifying EOwnerThread as the second parameter to this function, means that only the creating thread can use this handle to access the pipe.

Parameters

const TInt sSize
TOwnerType aType = EOwnerProcess The type of the handle to be created for the reading end of the pipe

Define(const TDesC &, TInt)

IMPORT_C TInt Define ( const TDesC & aName,
TInt aSize
) [static]

Support for named pipe

Static method to create a new, named pipe of a given size. Calling this method will create a new kernel object only. No user-side handles are created or opened.

Parameters

const TDesC & aName Name to be assigned to the Kernel-side pipe object.
TInt aSize Size of the pipe to create, in bytes.

Define(const TDesC &, TInt, const TSecurityPolicy &)

IMPORT_C TInt Define ( const TDesC & aName,
TInt aSize,
const TSecurityPolicy & aPolicy
) [static]

Static method to create a new, named pipe of a given size. Calling this method will create a new kernel object only. No user-side handles are created or opened.

Parameters

const TDesC & aName Name to be assigned to the Kernel-side pipe object.
TInt aSize Size of the pipe to create, in bytes.
const TSecurityPolicy & aPolicy

Destroy(const TDesC &)

IMPORT_C TInt Destroy ( const TDesC & aName ) [static]

Static method to destroy a previously created named pipe. Any data not read from the pipe will be discarded. This method will fail if there is any handles still open on the pipe or the calling thread as insufficient capabilities.

Parameters

const TDesC & aName Name of the Kernel-side pipe object to destroy

Flush()

IMPORT_C void Flush ( )

This method will empty the pipe of all data

HandleType()

IMPORT_C TInt HandleType ( ) const

This method returns the Type of operation it can perform with the current handle.

Init()

IMPORT_C TInt Init ( ) [static]

Static method to load the pipe device driver.

MaxSize()

IMPORT_C TInt MaxSize ( )

Returns the total size, in bytes, of the Pipe

Name()

const TDesC & Name ( ) [static, inline]

Returns the name of the DPipe factory object

NotifyDataAvailable(TRequestStatus &)

IMPORT_C void NotifyDataAvailable ( TRequestStatus & )

This method registers the request status object to be completed when data become available in the pipe.

Parameters

TRequestStatus & Status request that will complete when Data is available.

NotifySpaceAvailable(TInt, TRequestStatus &)

IMPORT_C void NotifySpaceAvailable ( TInt aSize,
TRequestStatus &
)

This method registers the request status object to be completed when at least aSize bytes are available for writing data into the pipe.

Parameters

TInt aSize Amount of space to wait for in the pipe.
TRequestStatus & Status request that will complete when aSize bytes become available.

Open(const RPipe &, TOwnerType)

TInt Open ( const RPipe & aWriter,
TOwnerType aType = EOwnerProcess
)

Opens a handle to write to a pipe. The pipe must have been created previously. By default any thread in the process can use the handle to access to write to the pipe. However, specifying EOwnerThread as the second parameter to this function, means that only the opening thread can use this handle to write to the pipe.

Parameters

const RPipe & aWriter Handle to the reading end of the pipe.
TOwnerType aType = EOwnerProcess The type of the handle to be created for the write end

Open(const TDesC &, TMode)

IMPORT_C TInt Open ( const TDesC & aName,
TMode aMode
)

Opens the pipe for the access mode specified. If the handle is opened to read or Write. The handle is opened regardless of whether or not there is a open handle at the other end.

If the handle is opened as " Write but Fail On No Readers" the call will fail unless there is atleast one handle open for reading at the other end.

Parameters

const TDesC & aName Name of the kernel-side pipe object to destroy
TMode aMode Access mode for the handle.

Open(TInt, TOwnerType)

IMPORT_C TInt Open ( TInt aArgumentIndex,
TOwnerType aType = EOwnerProcess
)

Opens the handle to pipe which is passed by a process to child process using RProcess.SetParameter function call. Pipe handle type remains same(i.e. if read handle is passed by process then read handle will be open).

Parameters

TInt aArgumentIndex An index that identifies the slot in the process environment data that contains the handle number. This is a value relative to zero, i.e. 0 is the first item/slot. This can range from 0 to 15.
TOwnerType aType = EOwnerProcess The type of the handle to be created for the read/write end

Open(RMessagePtr2, TInt, TOwnerType)

IMPORT_C TInt Open ( RMessagePtr2 aMessage,
TInt aParam,
TOwnerType aType = EOwnerProcess
)

Opens a handle to pipe using a handle number sent by a client to a server. This function is called by the server.

Parameters

RMessagePtr2 aMessage The message pointer.
TInt aParam An index specifying which of the four message arguments contains the handle number.
TOwnerType aType = EOwnerProcess An enumeration whose enumerators define the ownership of this logical channel handle. If not explicitly specified, EOwnerProcess is taken as default.

PipeHandle()

TInt PipeHandle ( ) const

Returns the id of Pipe it has created.

Read(TDes8 &, TInt)

IMPORT_C TInt Read ( TDes8 & aData,
TInt aSize
)

Non-blocking read/write operations

This is non-blocking synchronous method to read aNumByte bytes from the pipe into the descriptor aMsg and returns the number of bytes read. If the pipe is empty the call will immediately return a value of zero to indicate that no data was read

A successful RPipe::Read() operation will free up more space in the pipe.

Parameters

TDes8 & aData Descriptor to receive data
TInt aSize Number of bytes to be received.

ReadBlocking(TDes8 &, TInt)

IMPORT_C TInt ReadBlocking ( TDes8 & aData,
TInt aSize
)

Blocking read/write operations

This is synchronous, blocking read operation. If the pipe is empty the client thread will be blocked until data become available. A successful RPipe::ReadBlocking() operation will free up more space in the pipe. This method is accompanied by data notification method to complete the blocking mechanism

Parameters

TDes8 & aData Descriptor to receive data
TInt aSize Number of bytes to be received

ReqComplete(TRequestStatus &, TInt)

void ReqComplete ( TRequestStatus & aState,
TInt aval
) [private]

Parameters

TRequestStatus & aState
TInt aval

Size()

IMPORT_C TInt Size ( )

Returns the available data in the pipe

VersionRequired()

TVersion VersionRequired ( ) [static, inline]

Returns the version information of the DPipe Factory object

Wait(const TDesC &, TRequestStatus &)

IMPORT_C void Wait ( const TDesC & aName,
TRequestStatus & aStatus
)

Block the thread until the other end of the pipe is opened for reading. If the other end is already opened for reading the call will not block and status will complete immediately This function will be deprecated , use WaitForReader. Please note that Wait API will open a valid Write End of the pipe if not opened already. User need not open write end of the pipe again after Wait call.

Parameters

const TDesC & aName Name of the kernel-side pipe object to wait for
TRequestStatus & aStatus Status request that will complete when the other end is opened for reading.

Wait(const TDesC &, TRequestStatus &, TInt)

void Wait ( const TDesC & aName,
TRequestStatus & aStatus,
TInt aChoice
) [private]

Block the thread until the other end of the pipe is opened for reading (or writing). If the other end is already opened for reading (or writing) the call will not block and status will complete immediately.

Parameters

const TDesC & aName Name of the kernel-side pipe object to wait for
TRequestStatus & aStatus Status request that will complete when the other end is opened for reading (or Writing).
TInt aChoice EWaitForReader for WaitForReader. EWaitForWriter for WaitForWriter.

WaitForReader(const TDesC &, TRequestStatus &)

IMPORT_C void WaitForReader ( const TDesC & aName,
TRequestStatus & aStatus
)

Block the thread until the other end of the pipe is opened for reading. If the other end is already opened for reading the call will not block and status will complete immediately.

Please note that WaitForReader API will open a valid Write End of the pipe if not opened already. User need not open write end of the pipe again after WaitForReader call.

Parameters

const TDesC & aName Name of the kernel-side pipe object to wait for
TRequestStatus & aStatus Status request that will complete when the other end is opened for reading.

WaitForWriter(const TDesC &, TRequestStatus &)

IMPORT_C void WaitForWriter ( const TDesC & aName,
TRequestStatus & aStatus
)

Block the thread until the other end of the pipe is opened for writing. If the other end is already opened for writing the call will not block and status will complete immediately

Please note that WaitForWriter API will open a valid Read End of the pipe if not opened already. User need not open read end of the pipe again after WaitForWriter call.

Parameters

const TDesC & aName Name of the kernel-side pipe object to wait for
TRequestStatus & aStatus Status request that will complete when the other end is opened for writing.

Write(const TDesC8 &, TInt)

IMPORT_C TInt Write ( const TDesC8 & aBuf,
TInt aSize
)

This is non-blocking synchronous method to write data from aData. If the pipe is full it will return immediately with KErrOverFlow

Parameters

const TDesC8 & aBuf Descriptor from which data has to be written to the pipe
TInt aSize

WriteBlocking(const TDesC8 &, TInt)

IMPORT_C TInt WriteBlocking ( const TDesC8 & aBuf,
TInt aSize
)

This is a synchronous, blocking write operation. It will attempt to write aNumByte's worth of data to the pipe, waiting till space is available. If aNumByte is less than or equal to the pipe size, MaxSize() , the write shall be atomic (w.r.t other threads sharing this channel), otherwise the data will be split into multiple atomic writes of pipe size (except, of course, if less than MaxSize bytes of data remain to be written).

Parameters

const TDesC8 & aBuf Descriptor from which data has to be written to the pipe.
TInt aSize Amount of data to be written to the pipe

Member Enumerations Documentation

Enum TChannelType

Enumerators

EChannelUnset = 0x0
EReadChannel = 0x1
EWriteChannel = 0x2

Enum TMode

Enumeration for the modes of opening a pipe.

Enumerators

EOpenToRead
EOpenToWrite
EOpenToWriteNamedPipeButFailOnNoReaders

Enum TRequest

Enumerators

EDefineNamedPipe
EOpenToReadNamedPipe
EOpenToWriteNamedPipe
EOpenToWriteButFailOnNoReaderNamedPipe
EDestroyNamedPipe
ECreateUnNamedPipe
EOpenUnNamedPipe
ERead
EWrite
ESize
EReadBlocking
EWriteBlocking
EDataAvailable
EDataAvailableCount
ESpaceAvailable
EWaitNotification
EWaitNotificationCheck
ECancelSpaceAvailable
ECancelDataAvailable
ECancelWaitNotification
EFlushPipe
EClosePipe
EGetPipeInfo

Enum TWaitRequest

Enumerators

EWaitForReader
EWaitForWriter

Member Type Definitions Documentation

Typedef TPipeInfoBuf

typedef TPckgBuf < TPipeInfo > TPipeInfoBuf

Member Data Documentation

TInt iHandleType

TInt iHandleType [private]

TInt iPipeHandle

TInt iPipeHandle [private]

TInt iSize

TInt iSize [private]