symbianstream.h File Reference

Pre-condition

• aId must not be a NULL pointer

• aReturnHandle must not be a NULL pointer, and must point to writable storage for the handle.

• aId must be a valid active Surface ID created by the Surface Manager.

  • In particular, aId->IsNull() should return EFalse.

• Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.

Post-condition

• The location pointed to by aReturnHandle is set to a valid Native Stream object and KErrNone is returned, or NULL is set and an error code is returned appropriately.

• The method may fail due to memory allocation if the Native Stream does not already exist.

• If a stream object is successfully created, then the reference on the stream is increased to ensure it remains live following the method call. See SymbianStreamRemoveReference to release the reference.

Pre-condition

• aStream must be an active Native Stream object. It must not be NULL.

• aReturnBuffer must not be a NULL pointer, and must point to writable storage for the handle.

• Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.

• To simplify composition, SymbianStreamAcquireReadBuffer will never fail. It will arbitrarily select a buffer if the stream has never been written to or updated.

Post-condition

• This method always succeeds and returns quickly.

• The current read buffer is locked for reading.

• The location pointed to by aReturnBuffer is set to a handle representing the read buffer at the time of this call.

• Many readers may access the same buffer, but if the Native Stream represents a multi-buffered TSurfaceId content, writers are blocked from overwriting the current read buffer, which will be the last buffer successfully written to.

  • In single-buffered streams, the content of the buffer may be overwritten while the reader is reading it, leading to tearing, but this behavior is generally considered preferable to blocking the reader.

• The Native Stream will not be destroyed while buffers are acquired.

• Note that no operations likely to cause failure will occur during the acquire method, but successful acquire does not guarantee that the buffer pixel data can be successfully mapped using NativeStreamGetBufferPointer.

Pre-condition

• aStream must be an active Native Stream object. It must not be NULL.

• aReturnBuffer must not be a NULL pointer, and must point to writable storage for the handle.

• In single-buffered Native Streams, access is not controlled, any number of readers and/or writer(s) may access the buffer simultaneously, potentially leading to tearing, but this behavior is generally considered preferable to blocking the reader.

• In multi-buffered Native Streams, the next write buffer must be available, or the method call will fail and return an error. It may fail in three scenarios:

  • There is already an active writer

  • There are still readers attached to the next write buffer candidate (in buffer swapping architectures)

  • The copy from write buffer to read buffer is ongoing, or waiting for readers (in buffer copying architectures)

• Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.

Post-condition

• This method returns quickly.

• If the write buffer cannot be acquired immediately then an error code is returned, indicating why exclusive access to a writable buffer could not be obtained.

• If the write buffer is acquired the KErrNone is returned, and the contents referenced by aReturnBuffer are filled with a handle representing the current write buffer. The current write buffer is locked for writing.

• The Native Stream will not be destroyed while buffers are acquired.

• Note that no resource operations likely to cause failure will occur during the acquire method, but successful acquire does not guarantee that the buffer pixel data can be successfully mapped using NativeStreamGetBufferPointer.

 typedef void (*SymOwfStreamCallback)(
    SymbianStreamType, SymNativeStreamEvent, void*);

Pre-condition

• aStream must be an active Native Stream object. It must not be NULL.

• aObserver must not be NULL

• aData may be NULL

• The combination of observer and data may be already registered, in which case it will be called twice if an event occurs.

• Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.

Post-condition

• The method may fail to add the observer to an internal list of observers, due to memory failure.

• The observer function will be called when any event occurs which was specified in the OpenWF-C SI and has been implemented by OpenWF Support. Symbian OS-specific extension events will not be delivered to observers registering using this method.

Pre-condition

• aStream must be an active Native Stream object. It must not be NULL.

• aObserver must not be NULL

• aEvents must specify 1 or more event flags

• Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.

• aScreenNumber should be one of:

  • zero: Screen number 0 associated with the first on-screen composition context

  • positive: A real screen number associated other on-screen composition contexts

  • A good value for aScreenNumber may not be required for all event registrations, and should be set to EScreenNumberAllNoEvents when not required.

Post-condition

• The method may fail to add the observer to an internal list of observers, due to memory failure.

• The observer function will be called when an event specified in the parameter list occurs.

• If the screen number is zero or positive, or EScreenNumberAllEvents and the event includes ESOWF_EVENTUPDATED then this client may be expected to handle bit flagged events - see SymbianStreamEventBits. Such an Observer must also send back Available and Displayed notifications to Symbian Stream as required.

Pre-condition

• aStream must be an active Native Stream object. It must not be NULL.

Post-condition

• The object will not be destroyed until an equivalent number of calls to SymbianStreamRemoveReference.

Pre-condition

• aStream must be an active Native Stream object. It must not be NULL.

• aBufferHandle must be a valid acquired buffer on that native stream that has not yet been released.

• aReturnIndex must not be a NULL pointer, and must point to writable storage for the index value.

• aReturnSurface must not be a NULL pointer, and must point to writable storage for the TSurfaceId pointer.

• Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.

• SymbianStreamGetBufferPointer or SymbianStreamGetBufferId can only be called after a call to SymbianStreamAcquireReadBuffer or SymbianStreamAcquireWriteBuffer, and before the call to SymbianStreamReleaseReadBuffer or SymbianStreamReleaseWriteBuffer.

• They can be called multiple times in this period, but each call is not guaranteed to return the same information, and the information returned by an earlier call should not be used after repeating the call or after calling SymbianStreamReleaseReadBuffer or SymbianStreamReleaseWriteBuffer.

Pre-condition

• aId must not be NULL.

• aReturnStream must not be a NULL pointer, and must point to writable storage for the handle.

• [Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.]

Post-condition

• If a Native Stream has been successfully acquired, using SymbianStreamAcquire, for the surface ID, then that Native Stream is returned.

• The reference on the stream is increased to ensure it remains live following the method call. See SymbianStreamRemoveReference to release the reference.

• If the identified stream is not currently acquired, then NULL is returned, and an error code is set.

• The error codes set by this method may not distinguish between Surface IDs that have not been Acquired and bad values for the surface ID, such as IsNull() or destroyed surfaces.

Pre-condition

• aStream must be an active Native Stream object. It must not be NULL.

• aBuffer should not be NULL

• aReturnPointer must not be a NULL pointer, and must point to writable storage for the pointer.

• aBuffer must be a currently acquired read or write buffer handle on the specified Native Stream.

• Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.

• SymbianStreamGetBufferPointer or SymbianStreamGetBufferId should not be called more than once for each buffer acquire. Correct cleanup behavior is not guaranteed if these methods are called multiple times.

• The pixel data must be mappable to CPU-accessible RAM. For some multimedia content types this may not be possible, and the method will fail. The error reported will be forwarded from Surface Manager.

Post-condition

If unsuccessful, an error code is returned.

• The method may fail if the pixel data cannot be made available in the caller's address space, for a variety of reasons including running out of virtual memory. If Successful:

• Pixel data is made available and a pointer to the first pixel is returned.

• The layout of the pixel data will be as specified by SymbianStreamGetHeader.

• The memory may be tagged as read-only if the buffer was generated using AcquireReadBuffer.

• This layout implies a maximum size to the buffer data. The client should not access data outside that range of addresses.

Pre-condition

• aStream must be an active Native Stream object. It must not be NULL.

• The remaining parameters are each either NULL, or point to local data storage which will be modified.

Post-condition

• Targets of non-NULL parameters will be filled in with values describing the surface encapsulated by the Native Stream.

• [Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.]

• In the current implementation, this information is stored locally and can be efficiently accessed.

Pre-condition

• aStream must be an active Native Stream object. It must not be NULL.

• The remaining parameters are each either NULL, or point to local data storage which will be modified.

Post-condition

• Targets of non-NULL parameters will be filled in with the oversized buffer values described in the surface encapsulated by the Native Stream.

• If image stabilisation is not supported the displayable buffer size will be retrieved instead.

• [Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.]

• In the current implementation, this information is stored locally and can be efficiently accessed.

Pre-condition

• aStream must be an active Native Stream object. It must not be NULL.

• aBuffer should not be NULL.

• The remaining parameters are each either NULL, or point to local data storage which will be modified.

Post-condition

• Targets of non-NULL parameters will be filled in with the displayable offset values associated with the acquired buffer.

• The displayable offset is measured from the top left-hand corner of the oversized buffer to the top left-hand corner of the displayable sub rectangle.

• If image stabilisation is not supported or the offset is not used the displayable offset will be set to zero.

• [Calls can be safely made from any thread, but the same default heap must be in place for all calls. The thread should have an activated clean-up stack.]

• In the current implementation, this information is stored locally and can be efficiently accessed.