VST 3 Interfaces: IDataExchangeHandler Class Reference
Author: Steinberg

VST 3 Interfaces VST 3.7 SDK for developing VST plug-in

- Main Page
- Modules
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Macros Groups Pages
Public Member Functions | Static Public Attributes | List of all members
IDataExchangeHandler Class Referenceabstract

Host Data Exchange handler interface: Vst::IDataExchangeHandler. More...

`#include <ivstdataexchange.h>`

Inheritance diagram for IDataExchangeHandler:

## Public Member Functions
virtual tresult | openQueue (IAudioProcessor *processor, uint32 blockSize, uint32 numBlocks, uint32 alignment, DataExchangeUserContextID userContextID, DataExchangeQueueID *outID)=0
| open a new queue
virtual tresult | closeQueue (DataExchangeQueueID queueID)=0
| close a queue
virtual tresult | lockBlock (DataExchangeQueueID queueId, DataExchangeBlock *block)=0
| lock a block if available
virtual tresult | freeBlock (DataExchangeQueueID queueId, DataExchangeBlockID blockID, TBool sendToController)=0
| free a previously locked block
Public Member Functions inherited from FUnknown
virtual tresult | queryInterface (const TUID _iid, void **obj)=0
virtual uint32 | addRef ()=0
virtual uint32 | release ()=0

## Static Public Attributes
static const FUID | iid
Static Public Attributes inherited from FUnknown
static const FUID | iid

## Detailed Description

Host Data Exchange handler interface: Vst::IDataExchangeHandler.

- [host imp]
- [context interface]
- [released: 3.7.9]
- [optional]

The IDataExchangeHandler implements a direct and thread-safe connection from the realtime audio context of the audio processor to the non-realtime audio context of the edit controller. This should be used when the edit controller needs continuous data from the audio process for visualization or other use-cases. To circumvent the bottleneck on the main thread it is possible to configure the connection in a way that the calls to the edit controller will happen on a background thread.

Opening a queue: The main operation for a plug-in is to open a queue via the handler before the plug-in is activated (but it must be connected to the edit controller via the IConnectionPoint when the plug-in is using the recommended separation of edit controller and audio processor). The best place to do this is in the IAudioProcessor::setupProcessing method as this is also the place where the plug-in knows the sample rate and maximum block size which the plug-in may need to calculate the queue block size. When a queue is opened the edit controller gets a notification about it and the controller can decide if it wishes to receive the data on the main thread or the background thread.

Sending data: In the IAudioProcessor::process call the plug-in can now lock a block from the handler, fill it and when done free the block via the handler which then sends the block to the edit controller. The edit controller then receives the block either on the main thread or on a background thread depending on the setup of the queue. The host guarantees that all blocks are send before the plug-in is deactivated.

Closing a queue: The audio processor must close an opened queue and this has to be done after the processor was deactivated and before it is disconnected from the edit controller (see IConnectionPoint).

What to do when the queue is full and no block can be locked? The plug-in needs to be prepared for this situation as constraints in the overall system may cause the queue to get full. If you need to get this information to the controller you can declare a hidden parameter which you set to a special value and send this parameter change in your audio process method.

## Member Function Documentation

virtual tresult openQueue | ( | IAudioProcessor * | processor,
|  | uint32 | blockSize,
|  | uint32 | numBlocks,
|  | uint32 | alignment,
|  | DataExchangeUserContextID | userContextID,
|  | DataExchangeQueueID * | outID
| ) |  |
| pure virtual

open a new queue

only allowed to be called from the main thread when the component is not active but initialized and connected (see IConnectionPoint)

Parameters

  processor | the processor who wants to open the queue
  blockSize | size of one block
  numBlocks | number of blocks in the queue
  alignment | data alignment, if zero will use the platform default alignment if any
  userContextID | an identifier internal to the processor
  outID | on return the ID of the queue

Returns
  kResultTrue on success

virtual tresult closeQueue | ( | DataExchangeQueueID | queueID | ) |
| pure virtual

close a queue

closes and frees all memory of a previously opened queue if there are locked blocks in the queue, they are freed and made invalid

only allowed to be called from the main thread when the component is not active but initialized and connected

Parameters

  queueID | the ID of the queue to close

Returns
  kResultTrue on success

virtual tresult lockBlock | ( | DataExchangeQueueID | queueId,
|  | DataExchangeBlock * | block
| ) |  |
| pure virtual

lock a block if available

only allowed to be called from within the IAudioProcessor::process call

Parameters

  queueID | the ID of the queue
  block | on return will contain the data pointer and size of the block

Returns
  kResultTrue if a free block was found and kOutOfMemory if all blocks are locked

virtual tresult freeBlock | ( | DataExchangeQueueID | queueId,
|  | DataExchangeBlockID | blockID,
|  | TBool | sendToController
| ) |  |
| pure virtual

free a previously locked block

only allowed to be called from within the IAudioProcessor::process call

Parameters

  queueID | the ID of the queue
  blockID | the ID of the block
  sendToController | if true the block data will be send to the IEditController otherwise it will be discarded

Returns
  kResultTrue on success

## Member Data Documentation

const FUID iid
| static

Empty

Copyright ©2023 Steinberg Media Technologies GmbH. All Rights Reserved. This documentation is under this license.