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 TIntCancelDataAvailable()
IMPORT_C TIntCancelSpaceAvailable()
IMPORT_C voidCancelWait()
IMPORT_C voidClose()
IMPORT_C TIntCreate(TInt, RPipe &, RPipe &, TOwnerType, TOwnerType)
TInt Create(const TInt, TOwnerType)
IMPORT_C TIntDefine(const TDesC &, TInt)
IMPORT_C TIntDefine(const TDesC &, TInt, const TSecurityPolicy &)
IMPORT_C TIntDestroy(const TDesC &)
IMPORT_C voidFlush()
IMPORT_C TIntHandleType()
IMPORT_C TIntInit()
IMPORT_C TIntMaxSize()
const TDesC &Name()
IMPORT_C voidNotifyDataAvailable(TRequestStatus &)
IMPORT_C voidNotifySpaceAvailable(TInt, TRequestStatus &)
TInt Open(const RPipe &, TOwnerType)
IMPORT_C TIntOpen(const TDesC &, TMode)
IMPORT_C TIntOpen(TInt, TOwnerType)
IMPORT_C TIntOpen(RMessagePtr2, TInt, TOwnerType)
TInt PipeHandle()
IMPORT_C TIntRead(TDes8 &, TInt)
IMPORT_C TIntReadBlocking(TDes8 &, TInt)
IMPORT_C TIntSize()
TVersion VersionRequired()
IMPORT_C voidWait(const TDesC &, TRequestStatus &)
IMPORT_C voidWaitForReader(const TDesC &, TRequestStatus &)
IMPORT_C voidWaitForWriter(const TDesC &, TRequestStatus &)
IMPORT_C TIntWrite(const TDesC8 &, TInt)
IMPORT_C TIntWriteBlocking(const TDesC8 &, TInt)
Private Member Functions
voidReqComplete(TRequestStatus &, TInt)
voidWait(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
enumTChannelType { EChannelUnset = 0x0, EReadChannel = 0x1, EWriteChannel = 0x2 }
enumTMode { EOpenToRead, EOpenToWrite, EOpenToWriteNamedPipeButFailOnNoReaders }
enumTRequest {
EDefineNamedPipe, EOpenToReadNamedPipe, EOpenToWriteNamedPipe, EOpenToWriteButFailOnNoReaderNamedPipe, EDestroyNamedPipe, ECreateUnNamedPipe, EOpenUnNamedPipe, ERead, EWrite, ESize, EReadBlocking, EWriteBlocking, EDataAvailable, EDataAvailableCount, ESpaceAvailable, EWaitNotification, EWaitNotificationCheck, ECancelSpaceAvailable, ECancelDataAvailable, ECancelWaitNotification, EFlushPipe, EClosePipe, EGetPipeInfo
}
enumTWaitRequest { 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 TIntCancelDataAvailable()

Cancels an outstanding data available notifier request.

CancelSpaceAvailable()

IMPORT_C TIntCancelSpaceAvailable()

Cancels an outstanding space available notifier request.

CancelWait()

IMPORT_C voidCancelWait()

Cancel previous call to RPipe::Wait(), RPipe::WaitForReader (), RPipe::WaitForWriter ()

Close()

IMPORT_C voidClose()

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 TIntCreate(TIntaSize,
RPipe &aReader,
RPipe &aWriter,
TOwnerTypeaTypeR = EOwnerProcess,
TOwnerTypeaTypeW = 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 aSizeSize of the pipe to be created, in bytes.
RPipe & aReaderHandle to the read end of the pipe. If the call is successful, this handle will be opened for reading.
RPipe & aWriterHandle to the write end of the pipe. If the call is successful, this handle will be opened for writing.
TOwnerType aTypeR = EOwnerProcess
TOwnerType aTypeW = EOwnerProcessThe type of the ownership of the handle to be created for the read and write

Create(const TInt, TOwnerType)

TInt Create(const TIntsSize,
TOwnerTypeaType = 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 = EOwnerProcessThe type of the handle to be created for the reading end of the pipe

Define(const TDesC &, TInt)

IMPORT_C TIntDefine(const TDesC &aName,
TIntaSize
)[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 & aNameName to be assigned to the Kernel-side pipe object.
TInt aSizeSize of the pipe to create, in bytes.

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

IMPORT_C TIntDefine(const TDesC &aName,
TIntaSize,
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 & aNameName to be assigned to the Kernel-side pipe object.
TInt aSizeSize of the pipe to create, in bytes.
const TSecurityPolicy & aPolicy

Destroy(const TDesC &)

IMPORT_C TIntDestroy(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 & aNameName of the Kernel-side pipe object to destroy

Flush()

IMPORT_C voidFlush()

This method will empty the pipe of all data

HandleType()

IMPORT_C TIntHandleType()const

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

Init()

IMPORT_C TIntInit()[static]

Static method to load the pipe device driver.

MaxSize()

IMPORT_C TIntMaxSize()

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 voidNotifyDataAvailable(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 voidNotifySpaceAvailable(TIntaSize,
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 aSizeAmount 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,
TOwnerTypeaType = 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 & aWriterHandle to the reading end of the pipe.
TOwnerType aType = EOwnerProcessThe type of the handle to be created for the write end

Open(const TDesC &, TMode)

IMPORT_C TIntOpen(const TDesC &aName,
TModeaMode
)

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 & aNameName of the kernel-side pipe object to destroy
TMode aModeAccess mode for the handle.

Open(TInt, TOwnerType)

IMPORT_C TIntOpen(TIntaArgumentIndex,
TOwnerTypeaType = 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 aArgumentIndexAn 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 = EOwnerProcessThe type of the handle to be created for the read/write end

Open(RMessagePtr2, TInt, TOwnerType)

IMPORT_C TIntOpen(RMessagePtr2aMessage,
TIntaParam,
TOwnerTypeaType = 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 aMessageThe message pointer.
TInt aParamAn index specifying which of the four message arguments contains the handle number.
TOwnerType aType = EOwnerProcessAn 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 TIntRead(TDes8 &aData,
TIntaSize
)

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 & aDataDescriptor to receive data
TInt aSizeNumber of bytes to be received.

ReadBlocking(TDes8 &, TInt)

IMPORT_C TIntReadBlocking(TDes8 &aData,
TIntaSize
)

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 & aDataDescriptor to receive data
TInt aSizeNumber of bytes to be received

ReqComplete(TRequestStatus &, TInt)

voidReqComplete(TRequestStatus &aState,
TIntaval
)[private]

Parameters

TRequestStatus & aState
TInt aval

Size()

IMPORT_C TIntSize()

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 voidWait(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 & aNameName of the kernel-side pipe object to wait for
TRequestStatus & aStatusStatus request that will complete when the other end is opened for reading.

Wait(const TDesC &, TRequestStatus &, TInt)

voidWait(const TDesC &aName,
TRequestStatus &aStatus,
TIntaChoice
)[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 & aNameName of the kernel-side pipe object to wait for
TRequestStatus & aStatusStatus request that will complete when the other end is opened for reading (or Writing).
TInt aChoiceEWaitForReader for WaitForReader. EWaitForWriter for WaitForWriter.

WaitForReader(const TDesC &, TRequestStatus &)

IMPORT_C voidWaitForReader(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 & aNameName of the kernel-side pipe object to wait for
TRequestStatus & aStatusStatus request that will complete when the other end is opened for reading.

WaitForWriter(const TDesC &, TRequestStatus &)

IMPORT_C voidWaitForWriter(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 & aNameName of the kernel-side pipe object to wait for
TRequestStatus & aStatusStatus request that will complete when the other end is opened for writing.

Write(const TDesC8 &, TInt)

IMPORT_C TIntWrite(const TDesC8 &aBuf,
TIntaSize
)

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 & aBufDescriptor from which data has to be written to the pipe
TInt aSize

WriteBlocking(const TDesC8 &, TInt)

IMPORT_C TIntWriteBlocking(const TDesC8 &aBuf,
TIntaSize
)

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 & aBufDescriptor from which data has to be written to the pipe.
TInt aSizeAmount 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]