CHAI interface. More...

Public Member Functions
virtual void	Destroy ()=0
	Destroy the CHAI instance. More...

virtual void	GetVersion (CPNS::uint16 &wCHAIVersion, CPNS::uint16 &wVNMVersion)=0
	Get the current CHAI and VNM versions. More...

virtual CPNS::UTF8String	GetVersionString ()=0
	Get a string containing the current CHAI and VNM versions. More...

virtual CPNS::uint32	GetMachineUniqueDuplicateNumber ()=0
	Get unique duplicate related to the machine. More...

virtual CPNS::UTF8String	GetMachineName ()=0
	Get the machine name. More...

virtual CPNS::UTF8String	GetMachineMACAddress ()=0
	Get the machine MAC address. More...

virtual CPNS::MachineID	GetMachineID () const =0
	Get the machine ID. More...

virtual CPNS::uint32	GetRandom ()=0
	Get a random number Can be used to assign a random duplicate number to local devices. More...

virtual void	SetApplicationName (CPNS::char8 const *const utf8Name)=0
	Set the application name. More...

virtual void	SetMachineFitness (CPNS::uint8 const bFitnessValue)=0
	Set the machine fitness. More...

virtual void	CHAILock ()=0
	Lock the CHAI library This prevents the CHAI and related objects sending a notification or async return handler to the application. More...

virtual void	CHAIUnlock ()=0
	Unlock the CHAI library Restores the CHAI activity, handlers will be called again. More...

virtual void	SetThreadPriority (CPNS::uint8 const bPriority)=0
	Set the CHAI's thread priority. More...

virtual void	SetAsyncTimeouts (CPNS::boolean const fEnabled)=0
	Enable or disable the Async timeouts By default, Async operation timeout is enabled. More...

virtual void	SetTrashcanUsageForMessageObjects (CPNS::boolean const fEnabled)=0
	Enable or disable the trashcan usage for message objects By default, the trashcan is not used to maintain the message objects. More...

virtual void	SetCHAIDeviceFiltering (CPNS::boolean const fFiletered)=0
	Enable or disable the CHAI device filtering By default, CHAI devices PnP events are not notified to the application side. More...

virtual void	SetFlowControlIncomingCapacity (CPNS::uint32 const dwCapacity)=0
	Set the flow control incoming capacity By default, flow control capacity is infinite. More...

virtual void	FlowControl (CPNS::boolean const fSuspend)=0
	This can be used to notify connected Output that they should suspend or resume sending. More...

virtual CPNS::boolean	CheckAsync (CPNS::IAsync *const pAsync)=0
	Check if an async operation is still valid Verify if the async operation pointer is valid and can be used. More...

virtual CPNS::boolean	CancelAsync (CPNS::IAsync *const pAsync)=0
	Cancel an Async operation. More...

virtual void	RegisterNotificationHandler (CPNS::ICHAI_NotificationHandler *const pHandler)=0
	Register a CHAI's notification handler. More...

virtual void	UnregisterNotificationHandler (CPNS::ICHAI_NotificationHandler *const pHandler)=0
	Unregister a CHAI's notification handler. More...

virtual void	RegisterWatcherNotificationHandler (CPNS::CombinedWatcherPOIs const POIs, CPNS::ICHAI_WatcherNotificationHandler *const pHandler)=0
	Register a watcher notification handler. More...

virtual void	UnregisterWatcherNotificationHandler (CPNS::ICHAI_WatcherNotificationHandler *const pHandler)=0
	Unregister a watcher notification handler. More...

virtual CPNS::SystemTime	GetGlobalSynchronizedTime ()=0
	Get the current global synchronized time. More...

virtual CPNS::uint32	GetGlobalSynchronizedTimeMillisecond ()=0
	Get the current global synchronized time in milliseconds. More...

virtual CPNS::boolean	IsGlobalSynchronizedTimeReference ()=0
	Check if this machine is the current global synchronized time reference. More...

virtual CPNS::SystemTime	GetLocalTime ()=0
	Get the machine local time. More...

virtual CPNS::uint32	GetLocalTimeMillisec ()=0
	Get the machine local time in milliseconds. More...

virtual CPNS::Enums::Errors	EnterSnapshotSavingMode ()=0
	Enter in Snapshot saving mode. More...

virtual CPNS::Enums::Errors	EnterSnapshotRestoreMode ()=0
	Enter in Snapshot restore mode. More...

virtual void	LeaveSnapshotMode ()=0
	Quit the Snapshot mode if this is managed by the local CHAI! More...

virtual CPNS::Enums::SnapshotModes	GetCurrentSnapshotMode ()=0
	Check if a Snapshot mode is running. More...

virtual CPNS::IIndexList *	AddIndexList (CPNS::uint16 const wSize, CPNS::char8 const const const arutf8Names)=0
	Add a static Index List. More...

virtual CPNS::IIndexList *	AddIndexList (CPNS::uint16 const wSize, CPNS::IIndexList_NotificationHandler *const pHandler)=0
	Add an dynamic Index List. More...

virtual CPNS::boolean	RemoveIndexList (CPNS::IIndexList *const pList)=0
	Remove an Index List. More...

virtual CPNS::ISelectorItemList *	AddSelectorItemList (CPNS::uint16 const wSize, CPNS::SelectorItem const *const arItems)=0
	Add a static Selector Item List. More...

virtual CPNS::ISelectorItemList *	AddSelectorItemList (CPNS::uint16 const wSize, CPNS::ISelectorItemList_NotificationHandler *const pHandler)=0
	Add an dynamic Selector Item List. More...

virtual CPNS::boolean	RemoveSelectorItemList (CPNS::ISelectorItemList *const pList)=0
	Remove a Selector Item List. More...

virtual CPNS::boolean	RedeclareAllDevices ()=0
	Redeclare all devices. More...

virtual CPNS::ILocalDevice *	AddLocalDevice (CPNS::uint16 const wModelID, CPNS::uint32 const dwDuplicateNumber, CPNS::Enums::DuplicateModes const duplicateMode, CPNS::boolean const fHidden, CPNS::CombinedExtendedDeviceCapabilities const extDevCaps, CPNS::char8 const *const utf8ModelName)=0
	Add a new general purpose local device to the CHAI. More...

virtual CPNS::IMIDI2CPLocalDevice *	AddMIDI2CPLocalDevice (CPNS::uint16 const wModelID, CPNS::uint32 const dwDuplicateNumber, CPNS::Enums::DuplicateModes const duplicateMode, CPNS::boolean const fHidden, CPNS::CombinedExtendedDeviceCapabilities const extDevCaps, CPNS::char8 const *const utf8ModelName)=0
	Add a new MIDI -> CopperLan local device to the CHAI. More...

virtual CPNS::ICP2MIDILocalDevice *	AddCP2MIDILocalDevice (CPNS::uint16 const wModelID, CPNS::uint32 const dwDuplicateNumber, CPNS::Enums::DuplicateModes const duplicateMode, CPNS::boolean const fHidden, CPNS::CombinedExtendedDeviceCapabilities const extDevCaps, CPNS::char8 const *const utf8ModelName)=0
	Add a new CopperLan -> MIDI local device to the CHAI. More...

virtual CPNS::IHybridMIDILocalDevice *	AddHybridMIDILocalDevice (CPNS::uint16 const wModelID, CPNS::uint32 const dwDuplicateNumber, CPNS::Enums::DuplicateModes const duplicateMode, CPNS::boolean const fHidden, CPNS::CombinedExtendedDeviceCapabilities const extDevCaps, CPNS::char8 const *const utf8ModelName)=0
	Add a new CopperLan <-> MIDI local device to the CHAI. More...

virtual CPNS::IVMIDILinkOutLocalDevice *	AddVMIDILinkOutLocalDevice (CPNS::uint16 const wModelID, CPNS::uint32 const dwDuplicateNumber, CPNS::Enums::DuplicateModes const duplicateMode, CPNS::char8 const *const utf8PortName)=0
	Add a VMIDILink Out device. More...

virtual CPNS::IVMIDILinkInLocalDevice *	AddVMIDILinkInLocalDevice (CPNS::uint16 const wModelID, CPNS::uint32 const dwDuplicateNumber, CPNS::Enums::DuplicateModes const duplicateMode, CPNS::char8 const *const utf8PortName)=0
	Add a VMIDILink In sub-device This kind of Local Device is acting as a local input port, aimed to receive messages from a MIDI Out port automatically created on remote computers. More...

virtual CPNS::IVMIDILinkHybridLocalDevice *	AddVMIDILinkHybridLocalDevice (CPNS::uint16 const wModelID, CPNS::uint32 const dwDuplicateNumber, CPNS::Enums::DuplicateModes const duplicateMode, CPNS::char8 const *const utf8PortName)=0
	Add a VMIDILink Hybrid sub-device This kind of Local Device is acting as a local input/output port, aimed to receive and send messages from/to a pair of MIDI Out/In ports automatically created on remote computers. More...

virtual CPNS::ISharedDisplayLocalDevice *	AddSharedDisplayLocalDevice (CPNS::uint16 const wModelID, CPNS::uint32 const dwDuplicateNumber, CPNS::Enums::DuplicateModes const duplicateMode, CPNS::boolean const fHidden, CPNS::CombinedExtendedDeviceCapabilities const extDevCaps, CPNS::char8 const *const utf8ModelName)=0
	Add a new Shared Display local device to the CHAI. More...

virtual CPNS::ISharedDisplayClientLocalDevice *	AddSharedDisplayClientLocalDevice (CPNS::uint16 const wModelID, CPNS::uint32 const dwDuplicateNumber, CPNS::Enums::DuplicateModes const duplicateMode, CPNS::boolean const fHidden, CPNS::CombinedExtendedDeviceCapabilities const extDevCaps, CPNS::char8 const *const utf8ModelName)=0
	Add a new Shared Display Client local device to the CHAI. More...

virtual CPNS::IBaseLocalDevice *	GetLocalDevice (CPNS::DeviceID const &devID)=0
	Get a local device from its device ID. More...

virtual CPNS::boolean	RemoveLocalDevice (CPNS::IBaseLocalDevice const *const pDevice)=0
	Remove a local device. More...

virtual CPNS::Enums::Errors	Connect ()=0
	Get connected to the network. More...

virtual void	Disconnect ()=0
	Disconnected from the network. More...

virtual CPNS::boolean	IsConnected () const =0
	Check if the CHAI is connected. More...

virtual void	SetCHAIGroups (CPNS::uint32 const dwGroups)=0
	Set the CHAI groups. More...

virtual CPNS::uint32	GetCHAIGroups () const =0
	Get the CHAI groups. More...

virtual CPNS::IAsync *	RemoteDevice_FindFirst_Async (CPNS::CombinedFindDeviceOptions const options, CPNS::DeviceID const &parentDevID, CPNS::CombinedDeviceCapabilities const includeDeviceCapabilities, CPNS::CombinedDeviceCapabilities const excludeDeviceCapabilities, CPNS::ICHAI_RemoteDevice_Find_AsyncReturnHandler const pHandler, void const pUserPointer)=0
	Find the first device according the specified filtering arguments. More...

virtual CPNS::IAsync *	RemoteDevice_FindFirst_Async (CPNS::CombinedFindDeviceOptions const options, CPNS::DeviceID const &parentDevID, CPNS::CombinedDeviceCapabilities const includeDeviceCapabilities, CPNS::CombinedDeviceCapabilities const excludeDeviceCapabilities, CPNS::CombinedInOutCapabilities const includeInputCapabilities, CPNS::CombinedInOutCapabilities const excludeInputCapabilities, CPNS::CombinedInOutCapabilities const includeOutputCapabilities, CPNS::CombinedInOutCapabilities const excludeOutputCapabilities, CPNS::ICHAI_RemoteDevice_Find_AsyncReturnHandler const pHandler, void const pUserPointer)=0
	Find the first device according the specified filtering arguments. More...

virtual CPNS::IAsync *	RemoteDevice_FindFirst_Async (CPNS::CombinedFindDeviceOptions const options, CPNS::DeviceID const &parentDevID, CPNS::CombinedDeviceCapabilities const includeDeviceCapabilities, CPNS::CombinedDeviceCapabilities const excludeDeviceCapabilities, CPNS::CombinedInOutCapabilities const includeInputCapabilities, CPNS::CombinedInOutCapabilities const excludeInputCapabilities, CPNS::CombinedInOutCapabilities const includeOutputCapabilities, CPNS::CombinedInOutCapabilities const excludeOutputCapabilities, CPNS::uint16 const wBrandID, CPNS::uint16 const wModelID, CPNS::uint32 const dwDuplicateNumberFrom, CPNS::uint32 const dwDuplicateNumberTo, CPNS::uint16 const wModuleIDFrom, CPNS::uint16 const wModuleIDTo, CPNS::ICHAI_RemoteDevice_Find_AsyncReturnHandler const pHandler, void const pUserPointer)=0
	Find the first device according the specified filtering arguments. More...

virtual CPNS::IAsync *	RemoteDevice_FindNext_Async (CPNS::IDeviceEnumerationContext const pEnumerationContext, CPNS::ICHAI_RemoteDevice_Find_AsyncReturnHandler const pHandler, void *const pUserPointer)=0
	Find the next device according the specified enumeration context. More...

virtual CPNS::IAsync *	RemoteDevice_FindPrev_Async (CPNS::IDeviceEnumerationContext const pEnumerationContext, CPNS::ICHAI_RemoteDevice_Find_AsyncReturnHandler const pHandler, void *const pUserPointer)=0
	Find the previous device according the specified enumeration context. More...

virtual void	RegisterGlobalTimer (CPNS::CombinedGlobalTimerNotificationFlags const flags, CPNS::ICHAI_GlobalTimer_NotificationHandler *const pHandler)=0
	Register global timer notification handler for specified events. More...

virtual void	UnregisterGlobalTimer (CPNS::ICHAI_GlobalTimer_NotificationHandler *const pHandler)=0
	Unregister global timer notification handler. More...

virtual CPNS::ITimer *	AddTimer (CPNS::ICHAI_Timer_NotificationHandler *const pHandler)=0
	Add a timer. More...

virtual CPNS::boolean	RemoveTimer (CPNS::ITimer *const pTimer)=0
	Remove a timer. More...

virtual CPNS::Enums::Errors	Recording_Arm ()=0
	Global recording arming. More...

virtual CPNS::Enums::Errors	Recording_Arm (CPNS::DeviceID const &devID)=0
	Device recording arming. More...

virtual CPNS::Enums::Errors	Recording_Arm (CPNS::DeviceID const &devID, CPNS::uint16 const wOutputID_or_ControllerID)=0
	Output or Controller recording arming. More...

virtual CPNS::Enums::Errors	Recording_Disarm ()=0
	Global recording disarming. More...

virtual CPNS::Enums::Errors	Recording_Disarm (CPNS::DeviceID const &devID)=0
	Device recording disarming. More...

virtual CPNS::Enums::Errors	Recording_Disarm (CPNS::DeviceID const &devID, CPNS::uint16 const wOutputID_or_ControllerID)=0
	Output recording disarming. More...

virtual CPNS::Enums::Errors	Warning_Send (CPNS::Endpoint const &optionalSource, CPNS::CombinedWarningCodes const code, CPNS::Enums::WarningDomains const domain, CPNS::char8 const const utf8Title, CPNS::char8 const const utf8Content)=0
	Broadcast an warning message. More...

virtual void	RegisterSignalNotificationHandler (CPNS::ICHAI_SignalNotificationHandler *const pHandler)=0
	Register a Signal reception notification handler. More...

virtual void	UnregisterSignalNotificationHandler (CPNS::ICHAI_SignalNotificationHandler *const pHandler)=0
	Unregister a Signal reception notification handler. More...

virtual CPNS::Enums::Errors	Signal_Direct (CPNS::DeviceID const &devID, CPNS::uint16 const wSignalNumber, CPNS::uint16 const wOptionalData0, CPNS::uint16 const wOptionalData1, CPNS::uint16 const wOptionalData2, CPNS::uint16 const wOptionalData3, CPNS::char8 const *const utf8OptionalData, CPNS::Endpoint const &optionalEndpoint)=0
	Send a signal directed to the specified device from the CHAI. More...

virtual CPNS::Enums::Errors	Signal_Broadcast (CPNS::uint16 const wSignalNumber, CPNS::uint16 const wOptionalData0, CPNS::uint16 const wOptionalData1, CPNS::uint16 const wOptionalData2, CPNS::uint16 const wOptionalData3, CPNS::char8 const *const utf8OptionalData, CPNS::Endpoint const &optionalEndpoint)=0
	Send a signal broadcasted to all devices from the CHAI. More...

virtual CPNS::IRemoteDevice *	CreateRemoteDevice (CPNS::IBaseLocalDevice *const pLocalDevice)=0
	Create a new Remote Device object from a local device. More...

virtual CPNS::IRemoteDevice *	CreateRemoteDevice (CPNS::DeviceID const &devID, CPNS::IRemoteDevice_NotificationHandler *const pHandler)=0
	Create a new Remote Device object from a DeviceID. More...

virtual CPNS::IRemoteDevice *	CreateRemoteDevice (CPNS::Endpoint const &endPoint, CPNS::boolean const fEndpointIsSource, CPNS::IRemoteDevice_NotificationHandler2 *const pHandler)=0
	Create a new Remote Device object from an Endpoint. More...

virtual CPNS::IEventMessage *	CreateEventMessage ()=0
	Create a new Event Message object. More...

virtual CPNS::IEventMessage *	CreateEventMessage (CPNS::IEventMessage *const pCopySource)=0
	Create a new Event Message object. More...

virtual CPNS::IModifierMessage *	CreateModifierMessage ()=0
	Create a new Modifier Message object. More...

virtual CPNS::IModifierMessage *	CreateModifierMessage (CPNS::IModifierMessage *const pCopySource)=0
	Create a new Modifier Message object. More...

virtual CPNS::IModifierMessage *	CreateModifierMessage (CPNS::uint16 const wNumber, CPNS::uint16 const wIndex, CPNS::uint16 const wRawValue, CPNS::Enums::RelativeMode const relativeMode)=0
	Create a new Modifier Message object. More...

virtual CPNS::IModifierMessage *	CreateModifierMessage (CPNS::uint16 const wNumber, CPNS::uint16 const wIndex, CPNS::Value const &value, CPNS::Enums::RelativeMode const relativeMode)=0
	Create a new Modifier Message object. More...

virtual CPNS::ISelectorMessage *	CreateSelectorMessage ()=0
	Create a new Selector Message object. More...

virtual CPNS::ISelectorMessage *	CreateSelectorMessage (CPNS::uint16 const wNumber, CPNS::uint16 const wIndex, CPNS::uint16 const wRawValue, CPNS::Enums::RelativeMode const relativeMode)=0
	Create a new Selector Message object. More...

virtual CPNS::ITextMessage *	CreateTextMessage ()=0
	Create a new Text Message object. More...

virtual CPNS::ITextMessage *	CreateTextMessage (CPNS::uint16 const wNumber, CPNS::uint16 const wIndex, CPNS::char8 const *const utf8Text)=0
	Create a new Text Message object. More...

virtual CPNS::IMIDISysexMessage *	CreateMIDISysexMessage ()=0
	Create a new MIDI Sysex Message object. More...

virtual CPNS::IDataTransferMessage *	CreateDataTransferMessage ()=0
	Create a new Data Transfer Message object. More...

virtual CPNS::IDataTransferMessage *	CreateDataTransferMessage (CPNS::uint16 const wNumber)=0
	Create a new Data Transfer Message object. More...

Detailed Description

CHAI interface.

This is the CopperLan root object interface

Member Function Documentation

virtual CPNS::ICP2MIDILocalDevice* CPNS::ICHAI::AddCP2MIDILocalDevice	(	CPNS::uint16 const	wModelID,
		CPNS::uint32 const	dwDuplicateNumber,
		CPNS::Enums::DuplicateModes const	duplicateMode,
		CPNS::boolean const	fHidden,
		CPNS::CombinedExtendedDeviceCapabilities const	extDevCaps,
		CPNS::char8 const *const	utf8ModelName
	)

pure virtual

Add a new CopperLan -> MIDI local device to the CHAI.

Remarks: The returned pointer is related to an object handled by the CHAI; do not delete it! Using this method in connected mode implies usage of ICHAI::RedeclareAllDevices()

Parameters

[in]	wModelID	Device model ID code. This argument is not relevant if you provided a SDKKey during the CHAI creation. In this case the modelID is overridden by the one provided in the key.
[in]	dwDuplicateNumber	Preferred duplicate number for DM_Auto mode (might change in case of conflict), or requested number for DM_Fixed mode.
[in]	duplicateMode	Duplicate resolution mode
[in]	fHidden	TRUE if the device is hidden
[in]	extDevCaps	Combination of ExtendedDeviceCapabilities flags
[in]	utf8ModelName	Model name

Returns: a pointer to the new device object, or NULL if the device can't be added (in case of unsolved duplicate conflict, or if bad brand ID)

virtual CPNS::IHybridMIDILocalDevice* CPNS::ICHAI::AddHybridMIDILocalDevice	(	CPNS::uint16 const	wModelID,
		CPNS::uint32 const	dwDuplicateNumber,
		CPNS::Enums::DuplicateModes const	duplicateMode,
		CPNS::boolean const	fHidden,
		CPNS::CombinedExtendedDeviceCapabilities const	extDevCaps,
		CPNS::char8 const *const	utf8ModelName
	)

pure virtual

Add a new CopperLan <-> MIDI local device to the CHAI.

Remarks: The returned pointer is related to an object handled by the CHAI; do not delete it! Using this method in connected mode implies usage of ICHAI::RedeclareAllDevices()

Parameters

[in]	wModelID	Device model ID code. This argument is not relevant if you provided a SDKKey during the CHAI creation. In this case the modelID is overridden by the one provided in the key.
[in]	dwDuplicateNumber	Preferred duplicate number for DM_Auto mode (might change in case of conflict), or requested number for DM_Fixed mode.
[in]	duplicateMode	Duplicate resolution mode
[in]	fHidden	TRUE if the device is hidden
[in]	extDevCaps	Combination of ExtendedDeviceCapabilities flags
[in]	utf8ModelName	Model name

Returns: a pointer to the new device object, or NULL if the device can't be added (in case of unsolved duplicate conflict, or if bad brand ID)

virtual CPNS::IIndexList* CPNS::ICHAI::AddIndexList	(	CPNS::uint16 const	wSize,
		CPNS::char8 const const const	arutf8Names
	)

pure virtual

Add a static Index List.

Warning: This method is aimed to handle constant array of strings. The strings are not copied into the CHAI, so the CHAI is just keeping a pointer to the array!

Parameters

[in]	wSize	Number of items in the list
[in]	arutf8Names	Array of string pointers.

Returns: a pointer to the new index list object, or NULL if the list can't be added (not enough memory)

virtual CPNS::IIndexList* CPNS::ICHAI::AddIndexList	(	CPNS::uint16 const	wSize,
		CPNS::IIndexList_NotificationHandler *const	pHandler
	)

pure virtual

Add an dynamic Index List.

Warning: The content of this kind of list is collected through a callback. However the size of the list can't change during its lifetime.

Parameters

[in]	wSize	Number of items in the list
[in]	pHandler	Pointer to the application object implementing IIndexList_NotificationHandler

Returns: a pointer to the new index list object, or NULL if the list can't be added (not enough memory)

virtual CPNS::ILocalDevice* CPNS::ICHAI::AddLocalDevice	(	CPNS::uint16 const	wModelID,
		CPNS::uint32 const	dwDuplicateNumber,
		CPNS::Enums::DuplicateModes const	duplicateMode,
		CPNS::boolean const	fHidden,
		CPNS::CombinedExtendedDeviceCapabilities const	extDevCaps,
		CPNS::char8 const *const	utf8ModelName
	)

pure virtual

Add a new general purpose local device to the CHAI.

Remarks: The returned pointer is related to an object handled by the CHAI; do not delete it! Using this method in connected mode implies usage of ICHAI::RedeclareAllDevices()

Parameters

[in]	wModelID	Device model ID code. This argument is not relevant if you provided a SDKKey during the CHAI creation. In this case the modelID is overridden by the one provided in the key.
[in]	dwDuplicateNumber	Preferred duplicate number for DM_Auto mode (might change in case of conflict), or requested number for DM_Fixed mode.
[in]	duplicateMode	Duplicate resolution mode
[in]	fHidden	TRUE if the device is hidden
[in]	extDevCaps	Combination of ExtendedDeviceCapabilities flags
[in]	utf8ModelName	Model name

Returns: a pointer to the new device object, or NULL if the device can't be added (in case of unsolved duplicate conflict, or if bad brand ID)

virtual CPNS::IMIDI2CPLocalDevice* CPNS::ICHAI::AddMIDI2CPLocalDevice	(	CPNS::uint16 const	wModelID,
		CPNS::uint32 const	dwDuplicateNumber,
		CPNS::Enums::DuplicateModes const	duplicateMode,
		CPNS::boolean const	fHidden,
		CPNS::CombinedExtendedDeviceCapabilities const	extDevCaps,
		CPNS::char8 const *const	utf8ModelName
	)

pure virtual

Add a new MIDI -> CopperLan local device to the CHAI.

Remarks: The returned pointer is related to an object handled by the CHAI; do not delete it! Using this method in connected mode implies usage of ICHAI::RedeclareAllDevices()

Parameters

[in]	wModelID	Device model ID code. This argument is not relevant if you provided a SDKKey during the CHAI creation. In this case the modelID is overridden by the one provided in the key.
[in]	dwDuplicateNumber	Preferred duplicate number for DM_Auto mode (might change in case of conflict), or requested number for DM_Fixed mode.
[in]	duplicateMode	Duplicate resolution mode
[in]	fHidden	TRUE if the device is hidden
[in]	extDevCaps	Combination of ExtendedDeviceCapabilities flags
[in]	utf8ModelName	Model name

Returns: a pointer to the new device object, or NULL if the device can't be added (in case of unsolved duplicate conflict, or if bad brand ID)

virtual CPNS::ISelectorItemList* CPNS::ICHAI::AddSelectorItemList	(	CPNS::uint16 const	wSize,
		CPNS::SelectorItem const *const	arItems
	)

pure virtual

Add a static Selector Item List.

Warning: This method is aimed to handle constant array of items. The array content is not copied into the CHAI, so the CHAI is just keeping a pointer to the array!

Parameters

[in]	wSize	Number of items in the list
[in]	arItems	Array of Selector Item pointers.

Returns: a pointer to the new Selector Item list object, or NULL if the list can't be added (not enough memory)

virtual CPNS::ISelectorItemList* CPNS::ICHAI::AddSelectorItemList	(	CPNS::uint16 const	wSize,
		CPNS::ISelectorItemList_NotificationHandler *const	pHandler
	)

pure virtual

Add an dynamic Selector Item List.

Warning: The content of this kind of list is collected through a callback. However the size of the list can't change during its lifetime.

Parameters

[in]	wSize	Number of items in the list
[in]	pHandler	Pointer to the application object implementing ISelectorItemList_NotificationHandler

Returns: a pointer to the new Selector Item list object, or NULL if the list can't be added (not enough memory)

virtual CPNS::ISharedDisplayClientLocalDevice* CPNS::ICHAI::AddSharedDisplayClientLocalDevice	(	CPNS::uint16 const	wModelID,
		CPNS::uint32 const	dwDuplicateNumber,
		CPNS::Enums::DuplicateModes const	duplicateMode,
		CPNS::boolean const	fHidden,
		CPNS::CombinedExtendedDeviceCapabilities const	extDevCaps,
		CPNS::char8 const *const	utf8ModelName
	)

pure virtual

Add a new Shared Display Client local device to the CHAI.

Remarks: The returned pointer is related to an object handled by the CHAI; do not delete it! Using this method in connected mode implies usage of ICHAI::RedeclareAllDevices()

Parameters

[in]	wModelID	Device model ID code. This argument is not relevant if you provided a SDKKey during the CHAI creation. In this case the modelID is overridden by the one provided in the key.
[in]	dwDuplicateNumber	Preferred duplicate number for DM_Auto mode (might change in case of conflict), or requested number for DM_Fixed mode.
[in]	duplicateMode	Duplicate resolution mode
[in]	fHidden	TRUE if the device is hidden
[in]	extDevCaps	Combination of ExtendedDeviceCapabilities flags
[in]	utf8ModelName	Model name

Returns: a pointer to the new device object, or NULL if the device can't be added (in case of unsolved duplicate conflict, or if bad brand ID)

virtual CPNS::ISharedDisplayLocalDevice* CPNS::ICHAI::AddSharedDisplayLocalDevice	(	CPNS::uint16 const	wModelID,
		CPNS::uint32 const	dwDuplicateNumber,
		CPNS::Enums::DuplicateModes const	duplicateMode,
		CPNS::boolean const	fHidden,
		CPNS::CombinedExtendedDeviceCapabilities const	extDevCaps,
		CPNS::char8 const *const	utf8ModelName
	)

pure virtual

Add a new Shared Display local device to the CHAI.

Remarks: The returned pointer is related to an object handled by the CHAI; do not delete it! Using this method in connected mode implies usage of ICHAI::RedeclareAllDevices()

Parameters

[in]	wModelID	Device model ID code. This argument is not relevant if you provided a SDKKey during the CHAI creation. In this case the modelID is overridden by the one provided in the key.
[in]	dwDuplicateNumber	Preferred duplicate number for DM_Auto mode (might change in case of conflict), or requested number for DM_Fixed mode.
[in]	duplicateMode	Duplicate resolution mode
[in]	fHidden	TRUE if the device is hidden
[in]	extDevCaps	Combination of ExtendedDeviceCapabilities flags
[in]	utf8ModelName	Model name

Returns: a pointer to the new device object, or NULL if the device can't be added (in case of unsolved duplicate conflict, or if bad brand ID)

virtual CPNS::ITimer* CPNS::ICHAI::AddTimer ( CPNS::ICHAI_Timer_NotificationHandler *const pHandler )

pure virtual

Add a timer.

Parameters

[in] pHandler Pointer to the notification handler related to the new timer.

Returns: a pointer to the timer object. Use ITimer's methods to handle the timer.

virtual CPNS::IVMIDILinkHybridLocalDevice* CPNS::ICHAI::AddVMIDILinkHybridLocalDevice	(	CPNS::uint16 const	wModelID,
		CPNS::uint32 const	dwDuplicateNumber,
		CPNS::Enums::DuplicateModes const	duplicateMode,
		CPNS::char8 const *const	utf8PortName
	)

pure virtual

Add a VMIDILink Hybrid sub-device This kind of Local Device is acting as a local input/output port, aimed to receive and send messages from/to a pair of MIDI Out/In ports automatically created on remote computers.

Remarks: The returned pointer is related to an object handled by the CHAI; do not delete it! Using this method in connected mode implies usage of ICHAI::RedeclareAllDevices()

Warning: VMIDILink devices are automatically flagged as hidden

Parameters

[in]	wModelID	Device model ID code. This argument is not relevant if you provided a SDKKey during the CHAI creation. In this case the modelID is overridden by the one provided in the key.
[in]	dwDuplicateNumber	Preferred duplicate number for DM_Auto mode (might change in case of conflict), or requested number for DM_Fixed mode.
[in]	duplicateMode	Duplicate resolution mode
[in]	utf8PortName	The port name

Returns: a pointer to the new device object, or NULL if the device can't be added (in case of unsolved duplicate conflict, or if bad brand ID)

virtual CPNS::IVMIDILinkInLocalDevice* CPNS::ICHAI::AddVMIDILinkInLocalDevice	(	CPNS::uint16 const	wModelID,
		CPNS::uint32 const	dwDuplicateNumber,
		CPNS::Enums::DuplicateModes const	duplicateMode,
		CPNS::char8 const *const	utf8PortName
	)

pure virtual

Add a VMIDILink In sub-device This kind of Local Device is acting as a local input port, aimed to receive messages from a MIDI Out port automatically created on remote computers.

Remarks: The returned pointer is related to an object handled by the CHAI; do not delete it! Using this method in connected mode implies usage of ICHAI::RedeclareAllDevices()

Warning: VMIDILink devices are automatically flagged as hidden

Parameters

[in]	wModelID	Device model ID code. This argument is not relevant if you provided a SDKKey during the CHAI creation. In this case the modelID is overridden by the one provided in the key.
[in]	dwDuplicateNumber	Preferred duplicate number for DM_Auto mode (might change in case of conflict), or requested number for DM_Fixed mode.
[in]	duplicateMode	Duplicate resolution mode
[in]	utf8PortName	The port name

Returns: a pointer to the new device object, or NULL if the device can't be added (in case of unsolved duplicate conflict, or if bad brand ID)

virtual CPNS::IVMIDILinkOutLocalDevice* CPNS::ICHAI::AddVMIDILinkOutLocalDevice	(	CPNS::uint16 const	wModelID,
		CPNS::uint32 const	dwDuplicateNumber,
		CPNS::Enums::DuplicateModes const	duplicateMode,
		CPNS::char8 const *const	utf8PortName
	)

pure virtual

Add a VMIDILink Out device.

This kind of Local Device is acting as a local output port, aimed to send messages to a MIDI In port automatically created on remote computers.

Remarks: The returned pointer is related to an object handled by the CHAI; do not delete it! Using this method in connected mode implies usage of ICHAI::RedeclareAllDevices()

Warning: VMIDILink devices are automatically flagged as hidden

Parameters

[in]	wModelID	Device model ID code. This argument is not relevant if you provided a SDKKey during the CHAI creation. In this case the modelID is overridden by the one provided in the key.
[in]	dwDuplicateNumber	Preferred duplicate number for DM_Auto mode (might change in case of conflict), or requested number for DM_Fixed mode.
[in]	duplicateMode	Duplicate resolution mode
[in]	utf8PortName	The port name

Returns: a pointer to the new device object, or NULL if the device can't be added (in case of unsolved duplicate conflict, or if bad brand ID)

virtual CPNS::boolean CPNS::ICHAI::CancelAsync ( CPNS::IAsync *const pAsync )

pure virtual

Cancel an Async operation.

The async operation will be canceled, the related notification handler will be called with fSuccess at FALSE.

Parameters

[in] pAsync pointer to the IAsync object handling the async operation.

Returns: TRUE if the pointer is valid

Remarks: The CHAI checks pAsync validity before canceling the related async operation, so it is not an issue to pass an invalid pointer in case of bad pAsync handling in the application side (i.e. forget to reset the pointer at NULL on notification handler call)

virtual void CPNS::ICHAI::CHAILock ( )

pure virtual

Lock the CHAI library This prevents the CHAI and related objects sending a notification or async return handler to the application.

In other words, an application call Lock to ensure exclusive ownership of its resources for a while, without risk of those resource access from the CHAI's thread.

Warning: A call to CHAILock MUST BE FOLLOWED by a call to CHAIUnlock. Internal CHAI's activity is suspended, so it might result in timer accuracy lost. Locking the CHAI must be used for a very short time!

virtual void CPNS::ICHAI::CHAIUnlock ( )

pure virtual

Unlock the CHAI library Restores the CHAI activity, handlers will be called again.

virtual CPNS::boolean CPNS::ICHAI::CheckAsync ( CPNS::IAsync *const pAsync )

pure virtual

Check if an async operation is still valid Verify if the async operation pointer is valid and can be used.

Typically used within CHAILock/CHAIUnlock

Parameters

[in] pAsync pointer to the IAsync object handling the async operation.

Returns: TRUE if the pointer is valid

virtual CPNS::Enums::Errors CPNS::ICHAI::Connect ( )

pure virtual

Get connected to the network.

If this method is called when the CHAI is already connected, a redeclare of devices is performed.

Returns: CPNS::Enums::ERR_None | CPNS::Enums::ERR_FAILED

virtual CPNS::IDataTransferMessage* CPNS::ICHAI::CreateDataTransferMessage ( )

pure virtual

Create a new Data Transfer Message object.

Returns: a new object already acquired or NULL in case of error. The returned pointer must be released using its Release() method once useless.

virtual CPNS::IDataTransferMessage* CPNS::ICHAI::CreateDataTransferMessage ( CPNS::uint16 const wNumber )

pure virtual

Create a new Data Transfer Message object.

This method creates a new Data Transfer ready to be sent

Parameters

[in] wNumber message number, custom value or standard value DTN_*** from DataTransferNumbers enum

Returns: a new object already acquired or NULL in case of error. The returned pointer must be released using its Release() method once useless.

virtual CPNS::IEventMessage* CPNS::ICHAI::CreateEventMessage ( )

pure virtual

Create a new Event Message object.

Returns: a new object already acquired or NULL in case of error. The returned pointer must be released using its Release() method once useless.

virtual CPNS::IEventMessage* CPNS::ICHAI::CreateEventMessage ( CPNS::IEventMessage *const pCopySource )

pure virtual

Create a new Event Message object.

This method copy data from an existing event

Parameters

[in] pCopySource a pointer to the original Event

Returns: a new object already acquired or NULL in case of error. The returned pointer must be released using its Release() method once useless

virtual CPNS::IMIDISysexMessage* CPNS::ICHAI::CreateMIDISysexMessage ( )

pure virtual

Create a new MIDI Sysex Message object.

Returns: a new object already acquired or NULL in case of error. The returned pointer must be released using its Release() method once useless.

virtual CPNS::IModifierMessage* CPNS::ICHAI::CreateModifierMessage ( )

pure virtual

Create a new Modifier Message object.

Returns: a new object already acquired or NULL in case of error. The returned pointer must be released using its Release() method once useless.

virtual CPNS::IModifierMessage* CPNS::ICHAI::CreateModifierMessage ( CPNS::IModifierMessage *const pCopySource )

pure virtual

Create a new Modifier Message object.

This method copy data from an existing modifier

Parameters

[in] pCopySource a pointer to the original Modifier

Returns: a new object already acquired or NULL in case of error. The returned pointer must be released using its Release() method once useless

virtual CPNS::IModifierMessage* CPNS::ICHAI::CreateModifierMessage	(	CPNS::uint16 const	wNumber,
		CPNS::uint16 const	wIndex,
		CPNS::uint16 const	wRawValue,
		CPNS::Enums::RelativeMode const	relativeMode
	)

pure virtual

Create a new Modifier Message object.

This method creates a new Modifier ready to be sent

Parameters

[in]	wNumber	message number, custom value or standard value MOD_*** from Modifiers enum
[in]	wIndex	message index, 0 if no index.
[in]	wRawValue	raw value
[in]	relativeMode	specifies if the value is relative or not

Returns: a new object already acquired or NULL in case of error. The returned pointer must be released using its Release() method once useless

virtual CPNS::IModifierMessage* CPNS::ICHAI::CreateModifierMessage	(	CPNS::uint16 const	wNumber,
		CPNS::uint16 const	wIndex,
		CPNS::Value const &	value,
		CPNS::Enums::RelativeMode const	relativeMode
	)

pure virtual

Create a new Modifier Message object.

This method creates a new Modifier ready to be sent

Parameters

[in]	wNumber	message number, custom value or standard value MOD_*** from Modifiers enum
[in]	wIndex	message index, 0 if no index.
[in]	value	complete value (including raw value and optional typed value)
[in]	relativeMode	specifies if the value is relative or not

Returns: a new object already acquired or NULL in case of error. The returned pointer must be released using its Release() method once useless

virtual CPNS::IRemoteDevice* CPNS::ICHAI::CreateRemoteDevice ( CPNS::IBaseLocalDevice *const pLocalDevice )

pure virtual

Create a new Remote Device object from a local device.

Parameters

[in] pLocalDevice The local device pointer

Returns: a new object already acquired or NULL in case of error. The returned pointer must be released using its Release() method once useless.

virtual CPNS::IRemoteDevice* CPNS::ICHAI::CreateRemoteDevice	(	CPNS::DeviceID const &	devID,
		CPNS::IRemoteDevice_NotificationHandler *const	pHandler
	)

pure virtual

Create a new Remote Device object from a DeviceID.

The application is notified when additional information such as parent and capabilities is available.

Parameters

[in]	devID	The device ID
[in]	pHandler	Pointer to the application object implementing IRemoteDevice_NotificationHandler. Can be NULL if the remote device is just needed to perform immediate async operation.

Returns: a new object already acquired or NULL in case of error. The returned pointer must be released using its Release() method once useless.

Warning: It is very important to call IRemoteDevice::CancelSubTask if you want to abort a remote device creation in order to avoid a notification call to a destroyed object. On other words, it is not sufficient to release the remote device to abort its creation, because the underlying task performing information fetching will try to call a notification object that does not exist anymore.

virtual CPNS::IRemoteDevice* CPNS::ICHAI::CreateRemoteDevice	(	CPNS::Endpoint const &	endPoint,
		CPNS::boolean const	fEndpointIsSource,
		CPNS::IRemoteDevice_NotificationHandler2 *const	pHandler
	)

pure virtual

Create a new Remote Device object from an Endpoint.

The application is notified when additional information such as parent and capabilities is available. The notification informs also about the endpoint path.

Parameters

[in]	endPoint	The endpoint related to the expected device
[in]	fEndpointIsSource	TRUE if the endpoint is a source, FALSE is it is a destination
[in]	pHandler	Pointer to the application object implementing IRemoteDevice_NotificationHandler2

Returns: a new object already acquired or NULL in case of error. The returned pointer must be released using its Release() method once useless.

Warning: It is very important to call IRemoteDevice::CancelSubTask if you want to abort a remote device creation in order to avoid a notification call to a destroyed object. On other words, it is not sufficient to release the remote device to abort its creation, because the underlying task performing information fetching will try to call a notification object that does not exist anymore.

virtual CPNS::ISelectorMessage* CPNS::ICHAI::CreateSelectorMessage ( )

pure virtual

Create a new Selector Message object.

Returns: a new object already acquired or NULL in case of error. The returned pointer must be released using its Release() method once useless.

virtual CPNS::ISelectorMessage* CPNS::ICHAI::CreateSelectorMessage	(	CPNS::uint16 const	wNumber,
		CPNS::uint16 const	wIndex,
		CPNS::uint16 const	wRawValue,
		CPNS::Enums::RelativeMode const	relativeMode
	)

pure virtual

Create a new Selector Message object.

This method creates a new Selector ready to be sent

Parameters

[in]	wNumber	message number, custom value or standard value SEL_*** from Selectors enum
[in]	wIndex	message index, 0 if no index.
[in]	wRawValue	raw value
[in]	relativeMode	specifies if the value is relative or not

Returns: a new object already acquired or NULL in case of error. The returned pointer must be released using its Release() method once useless

virtual CPNS::ITextMessage* CPNS::ICHAI::CreateTextMessage ( )

pure virtual

Create a new Text Message object.

Returns: a new object already acquired or NULL in case of error. The returned pointer must be released using its Release() method once useless.

virtual CPNS::ITextMessage* CPNS::ICHAI::CreateTextMessage	(	CPNS::uint16 const	wNumber,
		CPNS::uint16 const	wIndex,
		CPNS::char8 const *const	utf8Text
	)

pure virtual

Create a new Text Message object.

This method creates a new Text ready to be sent

Parameters

[in]	wNumber	message number, custom value or standard value TXT_*** from Texts enum
[in]	wIndex	message index, 0 if no index.
[in]	utf8Text	text value

Returns: a new object already acquired or NULL in case of error. The returned pointer must be released using its Release() method once useless

virtual void CPNS::ICHAI::Destroy ( )

pure virtual

Destroy the CHAI instance.

Call this to destroy the CHAI instance and clear related memory.

Warning: after calling it, the CHAI pointer becomes invalid!

virtual void CPNS::ICHAI::Disconnect ( )

pure virtual

Disconnected from the network.

virtual CPNS::Enums::Errors CPNS::ICHAI::EnterSnapshotRestoreMode ( )

pure virtual

Enter in Snapshot restore mode.

The CHAI will maintain the network in Snapshot restore mode sending regularly a signal, so any application is aware about that, even it is declared on the network while a snapshot is running.

Returns: CPNS::Enums::ERR_None | CPNS::Enums::ERR_SnapshotInProgress

virtual CPNS::Enums::Errors CPNS::ICHAI::EnterSnapshotSavingMode ( )

pure virtual

Enter in Snapshot saving mode.

The CHAI will maintain the network in snapshot saving mode sending regularly a signal, so any application is aware about that, even it is declared on the network while a snapshot is running.

Returns: CPNS::Enums::ERR_None | CPNS::Enums::ERR_SnapshotInProgress

virtual void CPNS::ICHAI::FlowControl ( CPNS::boolean const fSuspend )

pure virtual

This can be used to notify connected Output that they should suspend or resume sending.

This is overriding the automatic flow control behavior. This method is offering the same functionality as CPNS::IBaseLocalDevice::FlowControl.

Parameters

[in] fSuspend TRUE if the connected Outputs should suspend sending

virtual CPNS::uint32 CPNS::ICHAI::GetCHAIGroups ( ) const

pure virtual

Get the CHAI groups.

Returns: the current Group flags

virtual CPNS::Enums::SnapshotModes CPNS::ICHAI::GetCurrentSnapshotMode ( )

pure virtual

Check if a Snapshot mode is running.

Returns: the current snapshot mode

virtual CPNS::SystemTime CPNS::ICHAI::GetGlobalSynchronizedTime ( )

pure virtual

Get the current global synchronized time.

Remarks: unit is 1 micro-second.

Returns: Global synchronized time.

virtual CPNS::uint32 CPNS::ICHAI::GetGlobalSynchronizedTimeMillisecond ( )

pure virtual

Get the current global synchronized time in milliseconds.

Returns: Global synchronized time in milliseconds

virtual CPNS::IBaseLocalDevice* CPNS::ICHAI::GetLocalDevice ( CPNS::DeviceID const & devID )

pure virtual

Get a local device from its device ID.

Parameters

[in] devID Requested device ID

Returns: pointer to the local device if exists, else NULL

virtual CPNS::SystemTime CPNS::ICHAI::GetLocalTime ( )

pure virtual

Get the machine local time.

Remarks: unit is 1 micro-second.

Returns: Machine local time.

virtual CPNS::uint32 CPNS::ICHAI::GetLocalTimeMillisec ( )

pure virtual

Get the machine local time in milliseconds.

Returns: Machine local time in milliseconds

virtual CPNS::MachineID CPNS::ICHAI::GetMachineID ( ) const

pure virtual

Get the machine ID.

Returns: the machine ID

virtual CPNS::UTF8String CPNS::ICHAI::GetMachineMACAddress ( )

pure virtual

Get the machine MAC address.

Returns: the machine MAC address string

virtual CPNS::UTF8String CPNS::ICHAI::GetMachineName ( )

pure virtual

Get the machine name.

Returns: the machine name string

virtual CPNS::uint32 CPNS::ICHAI::GetMachineUniqueDuplicateNumber ( )

pure virtual

Get unique duplicate related to the machine.

This value is calculated by platform dependend code. On Mac and PC, this value is the duplicated number identifying the local VNM Manager.

Returns: Machine unique ID, or 0 if not available

virtual CPNS::uint32 CPNS::ICHAI::GetRandom ( )

pure virtual

Get a random number Can be used to assign a random duplicate number to local devices.

Returns: a 32 bits random number

virtual void CPNS::ICHAI::GetVersion	(	CPNS::uint16 &	wCHAIVersion,
		CPNS::uint16 &	wVNMVersion
	)

pure virtual

Get the current CHAI and VNM versions.

This method is useful to identify the current CHAI and VNM versions. Version format is 0xMmbb, M: major, m: minor, bb: build. Ascendant compatibility is not guaranteed between different major versions.

Parameters

[out]	wCHAIVersion	Output argument receiving the CHAI version.
[out]	wVNMVersion	Output argument receiving the VNM version (if the CHAI is connected to the VNM)

virtual CPNS::UTF8String CPNS::ICHAI::GetVersionString ( )

pure virtual

Get a string containing the current CHAI and VNM versions.

Returns: A string formated "CHAI: version VNM: version"

virtual CPNS::boolean CPNS::ICHAI::IsConnected ( ) const

pure virtual

Check if the CHAI is connected.

Returns: TRUE if connected to the CopperLan network.

virtual CPNS::boolean CPNS::ICHAI::IsGlobalSynchronizedTimeReference ( )

pure virtual

Check if this machine is the current global synchronized time reference.

Returns: TRUE if it is the reference.

virtual void CPNS::ICHAI::LeaveSnapshotMode ( )

pure virtual

Quit the Snapshot mode if this is managed by the local CHAI!

Remarks: This method can't be used to terminate a Snapshot handled by another application on the network.

virtual CPNS::Enums::Errors CPNS::ICHAI::Recording_Arm ( )

pure virtual

Global recording arming.

Broadcasted to all outputs of all devices

Returns: CPNS::Enums::ERR_None | CPNS::Enums::ERR_FAILED

virtual CPNS::Enums::Errors CPNS::ICHAI::Recording_Arm ( CPNS::DeviceID const & devID )

pure virtual

Device recording arming.

Broadcasted to all outputs of the specified device

Parameters

[in] devID Device ID of the target device

Returns: CPNS::Enums::ERR_None | CPNS::Enums::ERR_FAILED

virtual CPNS::Enums::Errors CPNS::ICHAI::Recording_Arm	(	CPNS::DeviceID const &	devID,
		CPNS::uint16 const	wOutputID_or_ControllerID
	)

pure virtual

Output or Controller recording arming.

Sent to the specified Output or Controller of the specified device

Parameters

[in]	devID	Device ID of the target device
[in]	wOutputID_or_ControllerID	Output or Controller ID

Returns: CPNS::Enums::ERR_None | CPNS::Enums::ERR_FAILED

virtual CPNS::Enums::Errors CPNS::ICHAI::Recording_Disarm ( )

pure virtual

Global recording disarming.

Broadcasted to all outputs of all devices

Returns: CPNS::Enums::ERR_None | CPNS::Enums::ERR_FAILED

virtual CPNS::Enums::Errors CPNS::ICHAI::Recording_Disarm ( CPNS::DeviceID const & devID )

pure virtual

Device recording disarming.

Broadcasted to all outputs of the specified device

Parameters

[in] devID Device ID of the target device

Returns: CPNS::Enums::ERR_None | CPNS::Enums::ERR_FAILED

virtual CPNS::Enums::Errors CPNS::ICHAI::Recording_Disarm	(	CPNS::DeviceID const &	devID,
		CPNS::uint16 const	wOutputID_or_ControllerID
	)

pure virtual

Output recording disarming.

Sent to the specified Output or Controller of the specified device

Parameters

[in]	devID	Device ID of the target device
[in]	wOutputID_or_ControllerID	Output or Controller ID

Returns: CPNS::Enums::ERR_None | CPNS::Enums::ERR_FAILED

virtual CPNS::boolean CPNS::ICHAI::RedeclareAllDevices ( )

pure virtual

Redeclare all devices.

Returns: TRUE if succeeded

virtual void CPNS::ICHAI::RegisterGlobalTimer	(	CPNS::CombinedGlobalTimerNotificationFlags const	flags,
		CPNS::ICHAI_GlobalTimer_NotificationHandler *const	pHandler
	)

pure virtual

Register global timer notification handler for specified events.

Override previous registered flags for the specified handler.

Parameters

[in]	flags	Combination of GTNF_XXX flags
[in]	pHandler	Pointer to the application object implementing ICHAI_GlobalTimer_NotificationHandler

virtual void CPNS::ICHAI::RegisterNotificationHandler ( CPNS::ICHAI_NotificationHandler *const pHandler )

pure virtual

Register a CHAI's notification handler.

The CHAI's notification handler is used to send information to the application, such as connection status, device plug/unplug, ...

Parameters

[in] pHandler Pointer to the application object implementing ICHAI_NotificationHandler. If pHandler is NULL, clear all registered handlers.

virtual void CPNS::ICHAI::RegisterSignalNotificationHandler ( CPNS::ICHAI_SignalNotificationHandler *const pHandler )

pure virtual

Register a Signal reception notification handler.

Remarks: It is very important to unregister a notification handler before the pointer becomes invalid.

Parameters

[in] pHandler Pointer to the application object implementing ICHAI_SignalNotificationHandler Clear all registered handlers if pHandler is NULL.

virtual void CPNS::ICHAI::RegisterWatcherNotificationHandler	(	CPNS::CombinedWatcherPOIs const	POIs,
		CPNS::ICHAI_WatcherNotificationHandler *const	pHandler
	)

pure virtual

Register a watcher notification handler.

The watcher notification handler is used to notify the application when remote device connection status or controller assignment change.

Parameters

[in]	POIs	Bitfield containing the points of interest.
[in]	pHandler	Pointer to the application object implementing ICHAI_WatcherNotificationHandler. If pHandler is NULL, clear all registered handlers.

Remarks: The CHAI recall only the last POIs value. It means that if you register several global watchers, the CHAI uses the POIs value passed during the last registering call.

virtual CPNS::IAsync* CPNS::ICHAI::RemoteDevice_FindFirst_Async	(	CPNS::CombinedFindDeviceOptions const	options,
		CPNS::DeviceID const &	parentDevID,
		CPNS::CombinedDeviceCapabilities const	includeDeviceCapabilities,
		CPNS::CombinedDeviceCapabilities const	excludeDeviceCapabilities,
		CPNS::ICHAI_RemoteDevice_Find_AsyncReturnHandler *const	pHandler,
		void *const	pUserPointer
	)

pure virtual

Find the first device according the specified filtering arguments.

Parameters

[in]	parentDevID	Parent ID
[in]	includeDeviceCapabilities	Included device capabilities flags. Use DC_Any to keep all devices.
[in]	excludeDeviceCapabilities	Excluded device capabilities flags. Use DC_None to keep all devices.
[in]	pHandler	Pointer to the application object implementing ICHAI_RemoteDevice_Find_AsyncReturnHandler
[in]	pUserPointer	User data

Returns: A pointer to an IAsync object (see IAsync interface for more information on how to handle asynchronous call)

virtual CPNS::IAsync* CPNS::ICHAI::RemoteDevice_FindFirst_Async	(	CPNS::CombinedFindDeviceOptions const	options,
		CPNS::DeviceID const &	parentDevID,
		CPNS::CombinedDeviceCapabilities const	includeDeviceCapabilities,
		CPNS::CombinedDeviceCapabilities const	excludeDeviceCapabilities,
		CPNS::CombinedInOutCapabilities const	includeInputCapabilities,
		CPNS::CombinedInOutCapabilities const	excludeInputCapabilities,
		CPNS::CombinedInOutCapabilities const	includeOutputCapabilities,
		CPNS::CombinedInOutCapabilities const	excludeOutputCapabilities,
		CPNS::ICHAI_RemoteDevice_Find_AsyncReturnHandler *const	pHandler,
		void *const	pUserPointer
	)

pure virtual

Find the first device according the specified filtering arguments.

Parameters

[in]	options	Find options flags (FDO_XXX) combination.
[in]	parentDevID	Parent ID (not used if FDO_NoHierarchy is set)
[in]	includeDeviceCapabilities	Included device capabilities flags. Use DC_Any to keep all devices.
[in]	excludeDeviceCapabilities	Excluded device capabilities flags. Use DC_None to keep all devices.
[in]	includeInputCapabilities	Included input capabilities flags. Use IOC_Any to keep all devices.
[in]	excludeInputCapabilities	Excluded input capabilities flags. Use IOC_None to keep all devices.
[in]	includeOutputCapabilities	Included output capabilities flags. Use IOC_Any to keep all devices.
[in]	excludeOutputCapabilities	Excluded output capabilities flags. Use IOC_None to keep all devices.
[in]	pHandler	Pointer to the application object implementing ICHAI_RemoteDevice_Find_AsyncReturnHandler
[in]	pUserPointer	User data

Returns: A pointer to an IAsync object (see IAsync interface for more information on how to handle asynchronous call)

virtual CPNS::IAsync* CPNS::ICHAI::RemoteDevice_FindFirst_Async	(	CPNS::CombinedFindDeviceOptions const	options,
		CPNS::DeviceID const &	parentDevID,
		CPNS::CombinedDeviceCapabilities const	includeDeviceCapabilities,
		CPNS::CombinedDeviceCapabilities const	excludeDeviceCapabilities,
		CPNS::CombinedInOutCapabilities const	includeInputCapabilities,
		CPNS::CombinedInOutCapabilities const	excludeInputCapabilities,
		CPNS::CombinedInOutCapabilities const	includeOutputCapabilities,
		CPNS::CombinedInOutCapabilities const	excludeOutputCapabilities,
		CPNS::uint16 const	wBrandID,
		CPNS::uint16 const	wModelID,
		CPNS::uint32 const	dwDuplicateNumberFrom,
		CPNS::uint32 const	dwDuplicateNumberTo,
		CPNS::uint16 const	wModuleIDFrom,
		CPNS::uint16 const	wModuleIDTo,
		CPNS::ICHAI_RemoteDevice_Find_AsyncReturnHandler *const	pHandler,
		void *const	pUserPointer
	)

pure virtual

Find the first device according the specified filtering arguments.

Parameters

[in]	options	Find options flags (FDO_XXX) combination.
[in]	parentDevID	Parent ID (not used if FDO_NoHierarchy is set)
[in]	includeDeviceCapabilities	Included device capabilities flags. Use DC_Any to keep all devices.
[in]	excludeDeviceCapabilities	Excluded device capabilities flags. Use DC_None to keep all devices.
[in]	includeInputCapabilities	Included input capabilities flags. Use IOC_Any to keep all devices.
[in]	excludeInputCapabilities	Excluded input capabilities flags. Use IOC_None to keep all devices.
[in]	includeOutputCapabilities	Included output capabilities flags. Use IOC_Any to keep all devices.
[in]	excludeOutputCapabilities	Excluded output capabilities flags. Use IOC_None to keep all devices.
[in]	wBrandID	Brand ID filter. Use 0xFFFF as wildcard.
[in]	wModelID	Model ID filter. Use 0xFFFF as wildcard.
[in]	dwDuplicateNumberFrom	First duplicate number. Use 0xFFFFFFFF as wildcard.
[in]	dwDuplicateNumberTo	Last duplicate number. Use 0xFFFFFFFF as wildcard.
[in]	wModuleIDFrom	First module ID. Use 0xFFFF as wildcard.
[in]	wModuleIDTo	Last module ID. Use 0xFFFF as wildcard.
[in]	pHandler	Pointer to the application object implementing ICHAI_RemoteDevice_Find_AsyncReturnHandler
[in]	pUserPointer	User data

Returns: A pointer to an IAsync object (see IAsync interface for more information on how to handle asynchronous call)

virtual CPNS::IAsync* CPNS::ICHAI::RemoteDevice_FindNext_Async	(	CPNS::IDeviceEnumerationContext *const	pEnumerationContext,
		CPNS::ICHAI_RemoteDevice_Find_AsyncReturnHandler *const	pHandler,
		void *const	pUserPointer
	)

pure virtual

Find the next device according the specified enumeration context.

Parameters

[in]	pEnumerationContext	Enumeration context from previous ICHAI_RemoteDevice_Find_AsyncReturnHandler call
[in]	pHandler	Pointer to the application object implementing ICHAI_RemoteDevice_Find_AsyncReturnHandler
[in]	pUserPointer	User data

Returns: A pointer to an IAsync object (see IAsync interface for more information on how to handle asynchronous call)

virtual CPNS::IAsync* CPNS::ICHAI::RemoteDevice_FindPrev_Async	(	CPNS::IDeviceEnumerationContext *const	pEnumerationContext,
		CPNS::ICHAI_RemoteDevice_Find_AsyncReturnHandler *const	pHandler,
		void *const	pUserPointer
	)

pure virtual

Find the previous device according the specified enumeration context.

Parameters

[in]	pEnumerationContext	Enumeration context from previous ICHAI_RemoteDevice_Find_AsyncReturnHandler call
[in]	pHandler	Pointer to the application object implementing ICHAI_RemoteDevice_Find_AsyncReturnHandler
[in]	pUserPointer	User data

Returns: A pointer to an IAsync object (see IAsync interface for more information on how to handle asynchronous call)

virtual CPNS::boolean CPNS::ICHAI::RemoveIndexList ( CPNS::IIndexList *const pList )

pure virtual

Remove an Index List.

Remarks: Removing an Index List can make Parameters unusable! This can be used in case of Parameter set redefinition, but take care to re-create the related parameters after re-defining the lists.

Parameters

[in] pList Pointer to the list to remove.

Returns: TRUE on success

virtual CPNS::boolean CPNS::ICHAI::RemoveLocalDevice ( CPNS::IBaseLocalDevice const *const pDevice )

pure virtual

Remove a local device.

Remarks: Removing a parent device results in removing also all of its children. So be careful that children object handlers become invalid.

Parameters

[in] pDevice Pointer to the local device object to remove.

Returns: TRUE on success

Remarks: Removing a local device that is not a root device (a local device for which SetParent has been called with a non NULL pointer) might result in parent capabilities change. In this case, it is recommended to call the Root device's Declare() method to refresh its capabilities visibility over the network.

virtual CPNS::boolean CPNS::ICHAI::RemoveSelectorItemList ( CPNS::ISelectorItemList *const pList )

pure virtual

Remove a Selector Item List.

Remarks: Removing a Selector Item List can make Parameters unusable! This can be used in case of Parameter set redefinition, but take care to re-create the related parameters after re-defining the lists.

Parameters

[in] pList Pointer to the list to remove.

Returns: TRUE on success

virtual CPNS::boolean CPNS::ICHAI::RemoveTimer ( CPNS::ITimer *const pTimer )

pure virtual

Remove a timer.

Parameters

[in] pTimer Pointer to the timer object to remove.

Returns: TRUE on success

virtual void CPNS::ICHAI::SetApplicationName ( CPNS::char8 const *const utf8Name )

pure virtual

Set the application name.

The application name is used to identify the application over the network, for instance by warning messages to identify source in a friendly way. If no application name is set, the name of the first root is automatically used.

Parameters

[in] utf8Name Application name

virtual void CPNS::ICHAI::SetAsyncTimeouts ( CPNS::boolean const fEnabled )

pure virtual

Enable or disable the Async timeouts By default, Async operation timeout is enabled.

Parameters

[in] fEnabled TRUE to enable timeouts

virtual void CPNS::ICHAI::SetCHAIDeviceFiltering ( CPNS::boolean const fFiletered )

pure virtual

Enable or disable the CHAI device filtering By default, CHAI devices PnP events are not notified to the application side.

If means that CPNS::ICHAI_NotificationHandler virtual methods are not called for devices having BrandID 0x0001 and ModelID 0x0001.

virtual void CPNS::ICHAI::SetCHAIGroups ( CPNS::uint32 const dwGroups )

pure virtual

Set the CHAI groups.

Default group is 1.

Parameters

[in] dwGroups Group bit field: 31 LSB = one per group; MSB = super-group

virtual void CPNS::ICHAI::SetFlowControlIncomingCapacity ( CPNS::uint32 const dwCapacity )

pure virtual

Set the flow control incoming capacity By default, flow control capacity is infinite.

Remarks: This method must be called before device creation.

Parameters

[in] dwCapacity 0: (default value) infinite capacity, for computers. else available memory for incoming messaging

virtual void CPNS::ICHAI::SetMachineFitness ( CPNS::uint8 const bFitnessValue )

pure virtual

Set the machine fitness.

Warning: This can be used to change the machine fitness. Don't use this if you don't know exactly what is the machine fitness.

Parameters

[in] bFitnessValue Fitness value

virtual void CPNS::ICHAI::SetThreadPriority ( CPNS::uint8 const bPriority )

pure virtual

Set the CHAI's thread priority.

Warning: DO NOT USE THIS METHOD WITHOUT BEING AWARE OF THE CONSEQUENCES!!! In normal situation, use High value to ensure high reactivity and low latency. Use Normal if the application timing is more important than CopperLan operation. Low value should be used is very limited cases, knowing that there is a

Parameters

[in] bPriority 0: Low; 1: Normal; 2: High (default value)

virtual void CPNS::ICHAI::SetTrashcanUsageForMessageObjects ( CPNS::boolean const fEnabled )

pure virtual

Enable or disable the trashcan usage for message objects By default, the trashcan is not used to maintain the message objects.

Parameters

[in] fEnabled TRUE to enable thrashcan usage for message objects.

virtual CPNS::Enums::Errors CPNS::ICHAI::Signal_Broadcast	(	CPNS::uint16 const	wSignalNumber,
		CPNS::uint16 const	wOptionalData0,
		CPNS::uint16 const	wOptionalData1,
		CPNS::uint16 const	wOptionalData2,
		CPNS::uint16 const	wOptionalData3,
		CPNS::char8 const *const	utf8OptionalData,
		CPNS::Endpoint const &	optionalEndpoint
	)

pure virtual

Send a signal broadcasted to all devices from the CHAI.

Remarks: This method send broadcast signals. So the signal number MUST have SIGB_Broadcast bit set

Parameters

[in]	wSignalNumber	Standard Signal numbers are available from CPNS::Enums::Signals
[in]	wOptionalData0	Optional value, depending on the signal number
[in]	wOptionalData1	Optional value, depending on the signal number
[in]	wOptionalData2	Optional value, depending on the signal number
[in]	wOptionalData3	Optional value, depending on the signal number
[in]	utf8OptionalData	Optional value, depending on the signal number
[in]	optionalEndpoint	Optional value, depending on the signal number

Returns: CPNS::Enums::ERR_None | CPNS::Enums::ERR_BadSignalType | CPNS::Enums::ERR_NoDestination | CPNS::Enums::ERR_TooManyDestinations | CPNS::Enums::ERR_Failed

virtual CPNS::Enums::Errors CPNS::ICHAI::Signal_Direct	(	CPNS::DeviceID const &	devID,
		CPNS::uint16 const	wSignalNumber,
		CPNS::uint16 const	wOptionalData0,
		CPNS::uint16 const	wOptionalData1,
		CPNS::uint16 const	wOptionalData2,
		CPNS::uint16 const	wOptionalData3,
		CPNS::char8 const *const	utf8OptionalData,
		CPNS::Endpoint const &	optionalEndpoint
	)

pure virtual

Send a signal directed to the specified device from the CHAI.

Remarks: This method send directed signals. So the signal number MUST have SIGB_Directed bit set

Parameters

[in]	devID	Target Device ID
[in]	wSignalNumber	Standard Signal numbers are available from CPNS::Enums::Signals
[in]	wOptionalData0	Optional value, depending on the signal number
[in]	wOptionalData1	Optional value, depending on the signal number
[in]	wOptionalData2	Optional value, depending on the signal number
[in]	wOptionalData3	Optional value, depending on the signal number
[in]	utf8OptionalData	Optional value, depending on the signal number
[in]	optionalEndpoint	Optional value, depending on the signal number

Returns: CPNS::Enums::ERR_None | CPNS::Enums::ERR_BadSignalType | CPNS::Enums::ERR_NoDestination | CPNS::Enums::ERR_TooManyDestinations | CPNS::Enums::ERR_Failed

virtual void CPNS::ICHAI::UnregisterGlobalTimer ( CPNS::ICHAI_GlobalTimer_NotificationHandler *const pHandler )

pure virtual

Unregister global timer notification handler.

Parameters

[in] pHandler Pointer to the application object implementing ICHAI_GlobalTimer_NotificationHandler

virtual void CPNS::ICHAI::UnregisterNotificationHandler ( CPNS::ICHAI_NotificationHandler *const pHandler )

pure virtual

Unregister a CHAI's notification handler.

Parameters

[in] pHandler Pointer to the application object implementing ICHAI_NotificationHandler. If pHandler is NULL, clear all registered handlers.

virtual void CPNS::ICHAI::UnregisterSignalNotificationHandler ( CPNS::ICHAI_SignalNotificationHandler *const pHandler )

pure virtual

Unregister a Signal reception notification handler.

Remarks: It is very important to unregister a notification handler before the pointer becomes invalid.

Parameters

[in] pHandler Pointer to the application object implementing ICHAI_SignalNotificationHandler Clear all registered handlers if pHandler is NULL.

virtual void CPNS::ICHAI::UnregisterWatcherNotificationHandler ( CPNS::ICHAI_WatcherNotificationHandler *const pHandler )

pure virtual

Unregister a watcher notification handler.

Parameters

[in] pHandler Pointer to the application object implementing ICHAI_WatcherNotificationHandler. If pHandler is NULL, clear all registered handlers.

virtual CPNS::Enums::Errors CPNS::ICHAI::Warning_Send	(	CPNS::Endpoint const &	optionalSource,
		CPNS::CombinedWarningCodes const	code,
		CPNS::Enums::WarningDomains const	domain,
		CPNS::char8 const *const	utf8Title,
		CPNS::char8 const *const	utf8Content
	)

pure virtual

Broadcast an warning message.

Parameters

[in]	optionalSource	Optional source of the warning message
[in]	code	Combination of CPNS::Enums::WarningCodes values
[in]	domain	Related domain
[in]	utf8Title	Main description of the warning
[in]	utf8Content	Additional description of the warning

Returns: CPNS::Enums::ERR_None | CPNS::Enums::ERR_FAILED

Public Member Functions

Detailed Description

Member Function Documentation