ADTF  3.18.3
ISampleabstract

The ISample interface sets and retrieves properties on samples . More...

Inheritance diagram for ISample:
[legend]

Public Types

enum  eFlags : uint32_t {
  SF_None = 0x0 , SF_SyncPoint = 0x2 , SF_AbsoluteTime = 0x4 , SF_DataFromADTF1 = 0x8 ,
  SF_VideoKeyFrame = 0x10 , SF_SampleLogEnabled = 0x40 , SF_SampleLogPresent = 0x80 , SF_SampleInfoPresent = 0x100 ,
  SF_AllowBufferSharing = 0x400
}
 serval flags are defined All undefined bits are reserved for future and internal use. More...
 

Public Member Functions

 ADTF_IID (ISample, "sample.ant.streaming.adtf.iid")
 definition of interface id
 
virtual tResult Lock (ucom::ant::iobject_ptr_shared_locked< const ISampleBuffer > &oSampleBuffer) const =0
 Obtains a valid read-only reference to the sample buffer. More...
 
virtual tResult WriteLock (ucom::ant::iobject_ptr_locked< ISampleBuffer > &pSampleBuffer, size_t szPreAllocateSize)=0
 Obtains a valid reference to the sample buffer for writing access. More...
 
virtual tResult Set (const ISample &oSample)=0
 Deep copy the given sample (source) to this sample (destination). More...
 
virtual tResult Get (ISample &oSample) const =0
 Deep copy this sample (source) to the given sample (destination). More...
 
virtual tResult Reset ()=0
 Resets the whole sample content. More...
 
virtual uint32_t GetFlags () const =0
 Query sample flags. More...
 
virtual tResult SetFlags (uint32_t ui32Flags)=0
 Specify sample flags. More...
 
virtual tResult Set (tTimeStamp tmTimeStamp, const void *pData, size_t szSize, uint32_t ui32Flags=0)=0
 Sets the internal sample data and timestamp. More...
 
virtual tResult GetSampleBufferFactory (ucom::ant::iobject_ptr< ISampleBufferFactory > &oFactory) const =0
 Gets the SampleBufferFactory the Sample will ask for SampleBuffer to allocate. More...
 
virtual tResult GetSampleInfo (ucom::ant::iobject_ptr< const ISampleInfo > &oSampleInfo) const =0
 Gets the ISampleInfo of the sample. More...
 
virtual tResult GetSampleInfo (ucom::ant::iobject_ptr< ISampleInfo > &oSampleInfo)=0
 Gets the ISampleInfo of the sample. More...
 
virtual tResult GetSampleLog (ucom::ant::iobject_ptr< ISampleLog > &oSampleLog) const =0
 Gets the ISampleLog of the sample.
 
virtual tTimeStamp GetTime () const =0
 Retrieves the SampleTimeS (of StreamTime) of this sample. More...
 
virtual tResult SetTime (tTimeStamp tmTimeStamp)=0
 Sets the SampleTimeStamp (of StreamTime). More...
 
- Public Member Functions inherited from IObject
 ADTF_IID (IObject, "object.ant.ucom.adtf.iid")
 Marks the IObject to be castable with the ucom_cast() More...
 

Protected Member Functions

 ~ISample ()=default
 not destructable
 
- Protected Member Functions inherited from IObject
 ~IObject ()=default
 Protected destructor --> Use implemented Destroy() instead of delete!
 

Detailed Description

The ISample interface sets and retrieves properties on samples .

For information on realtime safety please have a look at the documentation of the default implementation adtf::streaming::ant::cSample.

See also
Sample.

Definition at line 34 of file sample_intf.h.

Member Enumeration Documentation

◆ eFlags

enum eFlags : uint32_t

serval flags are defined All undefined bits are reserved for future and internal use.

Enumerator
SF_None 

No flags are set.

SF_SyncPoint 

Determines if the sample marks a synchronization point.

Synchronization points can be used to seek inside the sample stream for things like key video frames. This flag will only be recognized by the HarddiskRecorder at the moment. Samples with this flag set will be set as IndexTable entry within the DAT File.
Use this flag with care!

SF_AbsoluteTime 

This flag has no effect and is only remaining due to code and binary compatibility purpose!

SF_DataFromADTF1 

If old ADTF V1.x data is stored, this flag will be set.

For own Sample implementations, the data has to be converted to ADTF V2 format After conversion, this flag has to be removed.

SF_VideoKeyFrame 

This flag marks key frames in video streams.

SF_SampleLogEnabled 

This flag marks that sample supports ISampleLog interface and it is enabled.

SF_SampleLogPresent 

This flag marks the sample supports the ISampleLog interface and a trace is present from Deserialization! (from network or DAT File !)

SF_SampleInfoPresent 

This flag marks the sample has the SampleInfo present.

SF_AllowBufferSharing 

mark that the buffer of this sample can be shared

Definition at line 48 of file sample_intf.h.

Member Function Documentation

◆ Get()

virtual tResult Get ( ISample oSample) const
pure virtual

Deep copy this sample (source) to the given sample (destination).

Parameters
[out]oSampleDestination sample
Returns
Standard Result Code
Return values
ERR_ACCESS_DENIEDgiven oSample is marked as readonly (see ISample::eFlags::SF_ReadOnly)

◆ GetFlags()

virtual uint32_t GetFlags ( ) const
pure virtual

Query sample flags.

The flags are XORed.

Returns
Flags specified for samples. See ISample::eFlags.

◆ GetSampleBufferFactory()

virtual tResult GetSampleBufferFactory ( ucom::ant::iobject_ptr< ISampleBufferFactory > &  oFactory) const
pure virtual

Gets the SampleBufferFactory the Sample will ask for SampleBuffer to allocate.

See also
Default implementation in cSample.
Parameters
[out]oFactoryThe buffer factory of the sample
Returns
Standard Result Code

◆ GetSampleInfo() [1/2]

virtual tResult GetSampleInfo ( ucom::ant::iobject_ptr< const ISampleInfo > &  oSampleInfo) const
pure virtual

Gets the ISampleInfo of the sample.

Parameters
[out]oSampleInfoThe sample info of the buffer
Returns
Standard Result Code

◆ GetSampleInfo() [2/2]

virtual tResult GetSampleInfo ( ucom::ant::iobject_ptr< ISampleInfo > &  oSampleInfo)
pure virtual

Gets the ISampleInfo of the sample.

Parameters
[out]oSampleInfoThe sample info of the buffer
Returns
Standard Result Code

◆ GetTime()

virtual tTimeStamp GetTime ( ) const
pure virtual

Retrieves the SampleTimeS (of StreamTime) of this sample.

The GetTime method retrieves the SampleTimeS (of StreamTime) of this sample.

Returns
Returns the SampleTimeS (of StreamTime) of this sample (see also Clock Concept for further infomation).
See also
Clock Concept

◆ Lock()

virtual tResult Lock ( ucom::ant::iobject_ptr_shared_locked< const ISampleBuffer > &  oSampleBuffer) const
pure virtual

Obtains a valid read-only reference to the sample buffer.

The Lock method obtains a valid reference to the sample buffer.

Remarks
The adtf::ucom::iobject_ptr_locked implementation with adtf::ucom::object_ptr_locked will automatically unlock on destruction.
Parameters
[out]oSampleBufferreference to set the buffer
Return values
ERR_POINTERoSampleBuffer.Reset failed
ERR_NOERROReverything is OK

Referenced by adtf::streaming::ant::read_from_sample().

◆ Reset()

virtual tResult Reset ( )
pure virtual

Resets the whole sample content.

Returns
Standard Result Code
Return values
ERR_ACCESS_DENIEDgiven sample is marked as readonly (see ISample::eFlags::SF_ReadOnly)

◆ Set() [1/2]

virtual tResult Set ( const ISample oSample)
pure virtual

Deep copy the given sample (source) to this sample (destination).

Parameters
[in]oSampleSource sample.
Returns
Standard Result Code
Return values
ERR_ACCESS_DENIEDsample is marked as readonly (see ISample::eFlags::SF_ReadOnly)

◆ Set() [2/2]

virtual tResult Set ( tTimeStamp  tmTimeStamp,
const void *  pData,
size_t  szSize,
uint32_t  ui32Flags = 0 
)
pure virtual

Sets the internal sample data and timestamp.

The method sets the internal data structures to new values. This is mainly used to deliver buffered sample data using preallocated sample objects.

Remarks
This is a shortcut for allocation a new buffer, putting a write lock onto its buffer, copying the data and unlocking the buffer. It is still recommended to allocate a new Sample each time you want to send one (see alloc_sample)
Parameters
tmTimeStamp[in] SampleTimestamp of (should be StreamTime).
pData[in] Pointer to the sample data which will be copied to it buffer.
szSize[in] Size of sample data, in bytes.
ui32Flags[in] Specifies the sample flags XORed.
Return values
ERR_ACCESS_DENIEDISample::eFlags::SF_ReadOnly is set.
ERR_NOERROReverything is OK
See also
Clock Concept
Remarks
The Parameter pData must not be a C++ object, use only raw memory, pointer to plain data types or plain old c-style structure definitions.

◆ SetFlags()

virtual tResult SetFlags ( uint32_t  ui32Flags)
pure virtual

Specify sample flags.

The flags are XORed.

Parameters
ui32Flags[in] Flag that specifies if the sample is a sync point or not. See ISample::eFlags.
Return values
ERR_NOERROReverything is OK
ERR_ACCESS_DENIEDISample::eFlags::SF_ReadOnly is set.

◆ SetTime()

virtual tResult SetTime ( tTimeStamp  tmTimeStamp)
pure virtual

Sets the SampleTimeStamp (of StreamTime).

Parameters
[in]tmTimeStampgiven timestamp (see also Clock Concept for further information on Times and StreamTime)
Return values
ERR_ACCESS_DENIEDISample::eFlags::SF_ReadOnly is set
ERR_NOERRORTime set
See also
Clock Concept

◆ WriteLock()

virtual tResult WriteLock ( ucom::ant::iobject_ptr_locked< ISampleBuffer > &  pSampleBuffer,
size_t  szPreAllocateSize 
)
pure virtual

Obtains a valid reference to the sample buffer for writing access.

The WriteLock method obtains a valid reference to the sample buffer.

Remarks
The adtf::ucom::iobject_ptr_locked implementation with adtf::ucom::object_ptr_locked will automatically unlock on destruction.
Warning
You must unlock the sample buffer before calling any write/flush call to the cSampleWriter. Otherwise it could be possible on synchronous calls the write lock is still valid while a reader wants to read from the buffer. This would fail.
Parameters
[out]pSampleBufferreference to the current sample buffer with writing access
[in]szPreAllocateSizeIf unequal to 0, will resize the the sample buffer to this size immediately. Otherwise the buffer is not modified at all.
Return values
ERR_POINTERpSampleBuffer is not valid
ERR_ACCESS_DENIEDsample is marked as readonly (see ISample::eFlags::SF_ReadOnly)
ERR_NOERROReverything is OK

Referenced by adtf::streaming::ant::write_to_sample().