api

type BindingEntry struct {
	Id            uint64
	ServerFeature FeatureLocalInterface
	ClientFeature FeatureRemoteInterface
}

type BindingManagerInterface interface {
	AddBinding(remoteDevice DeviceRemoteInterface, data model.BindingManagementRequestCallType) error
	RemoveBinding(data model.BindingManagementDeleteCallType, remoteDevice DeviceRemoteInterface) error
	RemoveBindingsForDevice(remoteDevice DeviceRemoteInterface)
	RemoveBindingsForEntity(remoteEntity EntityRemoteInterface)
	Bindings(remoteDevice DeviceRemoteInterface) []*BindingEntry
	BindingsOnFeature(featureAddress model.FeatureAddressType) []*BindingEntry
	HasLocalFeatureRemoteBinding(localAddress, remoteAddress *model.FeatureAddressType) bool
}

type ComControlInterface interface {
	// This must be connected to the correct remote device !!
	SendSpineMessage(datagram model.DatagramType) error
}

type DeviceInterface interface {
	// Get the device address
	Address() *model.AddressDeviceType
	// Get the device type
	DeviceType() *model.DeviceTypeType
	// Get the device feature set
	FeatureSet() *model.NetworkManagementFeatureSetType
	// Get the device destination data
	DestinationData() model.NodeManagementDestinationDataType
}

type DeviceLocalInterface interface {
	DeviceInterface
	// Setup a new remote device with a given SKI and triggers SPINE requesting device details
	SetupRemoteDevice(ski string, writeI shipapi.ShipConnectionDataWriterInterface) shipapi.ShipConnectionDataReaderInterface
	// Add a DeviceRemoteInterface implementation (used in SetupRemoteDevice and in tests)
	AddRemoteDeviceForSki(ski string, rDevice DeviceRemoteInterface)

	// Request NodeManagementDetailedDiscovery Data from a remote device
	RequestRemoteDetailedDiscoveryData(rDevice DeviceRemoteInterface) (*model.MsgCounterType, *model.ErrorType)

	// Remove a remote device and its connection
	RemoveRemoteDeviceConnection(ski string)
	// Remove a remote device (used in RemoveRemoteDeviceConnection and in tests)
	RemoveRemoteDevice(ski string)

	// Get a list of connected remote devices DeviceRemoteInterface implementations
	RemoteDevices() []DeviceRemoteInterface
	// Get a connected remote device DeviceRemoteInterface implementation for a given device address
	RemoteDeviceForAddress(address model.AddressDeviceType) DeviceRemoteInterface
	// Get a connected remote device DeviceRemoteInterface implementation for a SKI
	RemoteDeviceForSki(ski string) DeviceRemoteInterface

	// Add a new entity to the device
	// It should trigger a notification of all remote devices about this new entity
	AddEntity(entity EntityLocalInterface)
	// Remove a entity from the device
	// It should trigger a notification of all remote devices about this removed entity
	RemoveEntity(entity EntityLocalInterface)
	// Get a list of all entities EntityLocalInterface implementations
	Entities() []EntityLocalInterface
	// Get an entity EntityLocalInterface implementation for a given entity address
	Entity(id []model.AddressEntityType) EntityLocalInterface
	// Get the first entity EntityLocalInterface implementation for a given entity type
	EntityForType(entityType model.EntityTypeType) EntityLocalInterface

	// Get a FeatureLocalInterface implementation for a given feature address
	FeatureByAddress(address *model.FeatureAddressType) FeatureLocalInterface

	// Clean all entity specific caches
	CleanRemoteEntityCaches(remoteAddress *model.EntityAddressType)

	// Process incoming SPINE datagram
	ProcessCmd(datagram model.DatagramType, remoteDevice DeviceRemoteInterface) error

	// Get the node management
	NodeManagement() NodeManagementInterface

	// Get the bindings manager
	BindingManager() BindingManagerInterface

	// Get the subscription manager
	SubscriptionManager() SubscriptionManagerInterface
	// Send a notify message to remote device subscribing to a specific feature
	NotifySubscribers(featureAddress *model.FeatureAddressType, cmd model.CmdType)

	// Get the SPINE data structure for NodeManagementDetailDiscoveryData messages for this device
	Information() *model.NodeManagementDetailedDiscoveryDeviceInformationType
}

type DeviceRemoteInterface interface {
	DeviceInterface
	// Get the SKI of a remote device
	Ski() string

	// Add a new entity EntityRemoteInterface implementation
	AddEntity(entity EntityRemoteInterface)

	// Remove an entity for a given address and return the entity that was removed
	RemoveEntityByAddress(addr []model.AddressEntityType) EntityRemoteInterface

	// Get an entity EntityRemoteInterface implementation for a given address
	Entity(id []model.AddressEntityType) EntityRemoteInterface
	// Get all entities EntityRemoteInterface implementations
	Entities() []EntityRemoteInterface

	// Get a feature FeatureRemoteInterface implementation for a given address
	FeatureByAddress(address *model.FeatureAddressType) FeatureRemoteInterface
	// Get a feature FeatureRemoteInterface implementation from a given entity EntityRemoteInterface implementation by the feature type and feature role
	FeatureByEntityTypeAndRole(entity EntityRemoteInterface, featureType model.FeatureTypeType, role model.RoleType) FeatureRemoteInterface

	// Process incoming data payload
	HandleSpineMesssage(message []byte) (*model.MsgCounterType, error)

	// Get the SenderInterface implementation
	Sender() SenderInterface

	// Get the devices usecase data
	UseCases() []model.UseCaseInformationDataType

	// Update the devices address, type and featureset based on NetworkManagementDeviceDescriptionData
	UpdateDevice(description *model.NetworkManagementDeviceDescriptionDataType)

	// Add entities and their features using provided NodeManagementDetailedDiscoveryData
	AddEntityAndFeatures(initialData bool, data *model.NodeManagementDetailedDiscoveryDataType) ([]EntityRemoteInterface, error)

	// Helper method for checking incoming NodeManagementDetailedDiscoveryEntityInformation data
	CheckEntityInformation(initialData bool, entity model.NodeManagementDetailedDiscoveryEntityInformationType) error
}

type ElementChangeType uint16

type EntityInterface interface {
	// Get the entity address
	Address() *model.EntityAddressType
	// Get the entity type
	EntityType() model.EntityTypeType
	// Get the entity description
	Description() *model.DescriptionType
	// Set the entity description
	SetDescription(d *model.DescriptionType)
	// Get the next incremental feature id
	NextFeatureId() uint
}

type EntityLocalInterface interface {
	EntityInterface
	// Get the associated DeviceLocalInterface implementation
	Device() DeviceLocalInterface

	// Get the hearbeat manager for this entity
	HeartbeatManager() HeartbeatManagerInterface

	// Add a new feature with a given FeatureLocalInterface implementation
	AddFeature(f FeatureLocalInterface)
	// Get a FeatureLocalInterface implementation for a given feature type and role or create it if it does not exist yet and return it
	GetOrAddFeature(featureType model.FeatureTypeType, role model.RoleType) FeatureLocalInterface
	// Get a FeatureLocalInterface implementation for a given feature type and role
	FeatureOfTypeAndRole(featureType model.FeatureTypeType, role model.RoleType) FeatureLocalInterface
	// Get a FeatureLocalInterface implementation for a given feature address
	FeatureOfAddress(addressFeature *model.AddressFeatureType) FeatureLocalInterface
	// Get all FeatureLocalInterface implementations
	Features() []FeatureLocalInterface

	// Add a new usecase
	AddUseCaseSupport(
		actor model.UseCaseActorType,
		useCaseName model.UseCaseNameType,
		useCaseVersion model.SpecificationVersionType,
		useCaseDocumemtSubRevision string,
		useCaseAvailable bool,
		scenarios []model.UseCaseScenarioSupportType,
	)
	// Check if a use case is already added
	HasUseCaseSupport(
		actor model.UseCaseActorType,
		useCaseName model.UseCaseNameType) bool
	// Remove support for a usecase
	RemoveUseCaseSupport(
		actor model.UseCaseActorType,
		useCaseName model.UseCaseNameType,
	)
	// Set the availability of a usecase. This may only be used for usescases
	// that act as a client within the usecase!
	SetUseCaseAvailability(actor model.UseCaseActorType, useCaseName model.UseCaseNameType, available bool)
	// Remove all usecases
	RemoveAllUseCaseSupports()

	// Remove all subscriptions
	RemoveAllSubscriptions()

	// Remove all bindings
	RemoveAllBindings()

	// Get the SPINE data structure for NodeManagementDetailDiscoveryData messages for this entity
	Information() *model.NodeManagementDetailedDiscoveryEntityInformationType
}

type EntityRemoteInterface interface {
	EntityInterface

	// Get the associated DeviceRemoteInterface implementation
	Device() DeviceRemoteInterface

	// Update the device address (only used for the DeviceInformation entity when receiving the DetailDiscovery reply)
	UpdateDeviceAddress(address model.AddressDeviceType)

	// Add a new feature with a given FeatureLocalInterface implementation
	AddFeature(f FeatureRemoteInterface)

	// Remove all features
	RemoveAllFeatures()

	// Get a FeatureRemoteInterface implementation for a given feature type and role
	FeatureOfTypeAndRole(featureType model.FeatureTypeType, role model.RoleType) FeatureRemoteInterface
	// Get a FeatureRemoteInterface implementation for a given feature address
	FeatureOfAddress(addressFeature *model.AddressFeatureType) FeatureRemoteInterface
	// Get all FeatureRemoteInterface implementations
	Features() []FeatureRemoteInterface
}

type EventHandlerInterface interface {
	HandleEvent(EventPayload)
}

type EventHandlerLevel uint

type EventPayload struct {
	Ski           string                // required
	EventType     EventType             // required
	ChangeType    ElementChangeType     // required
	Device        DeviceRemoteInterface // required for DetailedDiscovery Call
	Entity        EntityRemoteInterface // required for DetailedDiscovery Call and Notify
	Feature       FeatureRemoteInterface
	LocalFeature  FeatureLocalInterface    // required for write commands
	Function      model.FunctionType       // required for write commands
	CmdClassifier *model.CmdClassifierType // optional, used together with EventType EventTypeDataChange
	Data          any
}

type EventType uint16

type FeatureInterface interface {
	// Get the feature address
	Address() *model.FeatureAddressType
	// Get the feature type
	Type() model.FeatureTypeType
	// Get the feature role
	Role() model.RoleType
	// Get the feature operations
	Operations() map[model.FunctionType]OperationsInterface
	// Get the feature description
	Description() *model.DescriptionType
	// Set the feature description with a given type
	SetDescription(desc *model.DescriptionType)
	// Set the feature description with a given string
	SetDescriptionString(s string)
	// Return a descriptive feature summary as a string
	String() string
}

type FeatureLocalInterface interface {
	FeatureInterface
	// Get the associated DeviceLocalInterface implementation
	Device() DeviceLocalInterface
	// Get the associated EntityLocalInterface implementation
	Entity() EntityLocalInterface

	// Add a function type with allowed operations
	AddFunctionType(function model.FunctionType, read, write bool)
	// Add a callback function to be invoked when SPINE message comes in with a given msgCounterReference value
	//
	// Returns an error if there is already a callback for the msgCounter set
	AddResponseCallback(msgCounterReference model.MsgCounterType, function func(msg ResponseMessage)) error
	// Add a callback function to be invoked when a result message comes in for this feature
	AddResultCallback(function func(msg ResponseMessage))

	// Add a callback method for a server feature which is invoked to
	// check wether an incoming write message shall be approved or denied
	AddWriteApprovalCallback(function WriteApprovalCallbackFunc) error
	// This function needs to be invoked within (default) 10 seconds after the via
	// AddWriteApprovalCallback defined callback is being invoked.
	//
	// NOTE: To approve a write, ALL callbacks need to approve the write!
	//
	// ErrorType.ErrorNumber should be 0 if write is approved
	ApproveOrDenyWrite(msg *Message, err model.ErrorType)
	// Overwrite the default 1 minute timeout for write approvals
	SetWriteApprovalTimeout(duration time.Duration)

	// Clean all write approval caches for a remote device ski
	CleanWriteApprovalCaches(ski string)
	// Clean all remote device specific caches
	CleanRemoteDeviceCaches(remoteAddress *model.DeviceAddressType)
	// Clean all remote entity specific caches
	CleanRemoteEntityCaches(remoteAddress *model.EntityAddressType)

	// return all functions
	Functions() []model.FunctionType

	// Get a copy of the features data for a given function type
	DataCopy(function model.FunctionType) any
	// Update the features data for a given function type
	UpdateData(function model.FunctionType, data any, filterPartial *model.FilterType, filterDelete *model.FilterType) *model.ErrorType
	// Set the features data for a given function type
	SetData(function model.FunctionType, data any)

	// Trigger a read request message for a given FeatureRemoteInterface implementation
	RequestRemoteData(
		function model.FunctionType,
		selector any,
		elements any,
		destination FeatureRemoteInterface) (*model.MsgCounterType, *model.ErrorType)
	// Trigger a read request message for a remote ski and feature address
	RequestRemoteDataBySenderAddress(
		cmd model.CmdType,
		sender SenderInterface,
		destinationSki string,
		destinationAddress *model.FeatureAddressType,
		maxDelay time.Duration) (*model.MsgCounterType, *model.ErrorType)

	// Check if there already is a subscription to a given feature remote address
	HasSubscriptionToRemote(remoteAddress *model.FeatureAddressType) bool
	// Trigger a subscription request to a given feature remote address
	SubscribeToRemote(remoteAddress *model.FeatureAddressType) (*model.MsgCounterType, *model.ErrorType)
	// Trigger a subscription removal request for a given feature remote address
	RemoveRemoteSubscription(remoteAddress *model.FeatureAddressType) (*model.MsgCounterType, *model.ErrorType)
	// Trigger subscription removal requests for all subscriptions of this feature
	RemoveAllRemoteSubscriptions()

	// Check if there already is a binding to a given feature remote address
	HasBindingToRemote(remoteAddress *model.FeatureAddressType) bool
	// Trigger a binding request to a given feature remote address
	BindToRemote(remoteAddress *model.FeatureAddressType) (*model.MsgCounterType, *model.ErrorType)
	// Trigger a binding removal request for a given feature remote address
	RemoveRemoteBinding(remoteAddress *model.FeatureAddressType) (*model.MsgCounterType, *model.ErrorType)
	// Trigger binding removal requests for all subscriptions of this feature
	RemoveAllRemoteBindings()

	// Handle an incoming SPINE message for this feature
	HandleMessage(message *Message) *model.ErrorType

	// Get the SPINE data structure for NodeManagementDetailDiscoveryData messages for this feature
	Information() *model.NodeManagementDetailedDiscoveryFeatureInformationType
}

type FeatureRemoteInterface interface {
	FeatureInterface

	// Get the associated DeviceRemoteInterface implementation
	Device() DeviceRemoteInterface
	// Get the associated EntityRemoteInterface implementation
	Entity() EntityRemoteInterface

	// Get a copy of the features data for a given function type
	DataCopy(function model.FunctionType) any
	// Set the features data for a given function type
	// persist true will store the data, false will return the updated data without storing it
	UpdateData(persist bool, function model.FunctionType, data any, filterPartial *model.FilterType, filterDelete *model.FilterType) (any, *model.ErrorType)

	// Set the supported operations of the feature for a set of functions
	SetOperations(functions []model.FunctionPropertyType)

	// Define the maximum response duration
	SetMaxResponseDelay(delay *model.MaxResponseDelayType)
	// Get the maximum allowed response duration
	MaxResponseDelayDuration() time.Duration
}

type FunctionDataCmdInterface interface {
	FunctionDataInterface
	// Get the CmdType data for a read command
	//
	// Note: partialSelector and elements have to be pointers!
	ReadCmdType(partialSelector any, elements any) model.CmdType
	// Get the CmdType data for a reply command
	ReplyCmdType(partial bool) model.CmdType
	// Get the CmdType data for a notify or write command
	//
	// Note: partialSelector and elements have to be pointers!
	NotifyOrWriteCmdType(deleteSelector, partialSelector any, partialWithoutSelector bool, deleteElements any) model.CmdType
}

type FunctionDataInterface interface {
	// Get the function type
	FunctionType() model.FunctionType
	// Return if this function supports partial writes
	SupportsPartialWrite() bool
	// Get a copy of the functions data
	DataCopyAny() any
	// Update the functions data, only persisted if persist is true, otherwise useful for creating full write datasets
	UpdateDataAny(remoteWrite, persist bool, data any, filterPartial *model.FilterType, filterDelete *model.FilterType) (any, *model.ErrorType)
}

type HeartbeatManagerInterface interface {
	IsHeartbeatRunning() bool
	SetLocalFeature(entity EntityLocalInterface, feature FeatureLocalInterface)
	StartHeartbeat() error
	StopHeartbeat()
}

type Message struct {
	RequestHeader *model.HeaderType
	CmdClassifier model.CmdClassifierType
	Cmd           model.CmdType
	FilterPartial *model.FilterType
	FilterDelete  *model.FilterType
	FeatureRemote FeatureRemoteInterface
	EntityRemote  EntityRemoteInterface
	DeviceRemote  DeviceRemoteInterface
}

type NodeManagementInterface interface {
	FeatureLocalInterface
}

type OperationsInterface interface {
	Write() bool
	WritePartial() bool
	Read() bool
	ReadPartial() bool
	String() string
	Information() *model.PossibleOperationsType
}

type ResponseMessage struct {
	MsgCounterReference model.MsgCounterType   // required
	Data                any                    // required
	FeatureLocal        FeatureLocalInterface  // required
	FeatureRemote       FeatureRemoteInterface // required
	EntityRemote        EntityRemoteInterface  // required
	DeviceRemote        DeviceRemoteInterface  // required
}

type SenderInterface interface {
	// Process a received message, e.g. for handling caching data
	ProcessResponseForMsgCounterReference(msgCounterRef *model.MsgCounterType)
	// Sends a read cmd to request some data
	Request(cmdClassifier model.CmdClassifierType, senderAddress, destinationAddress *model.FeatureAddressType, ackRequest bool, cmd []model.CmdType) (*model.MsgCounterType, error)
	// Sends a result cmd with no error to indicate that a message was processed successfully
	ResultSuccess(requestHeader *model.HeaderType, senderAddress *model.FeatureAddressType) error
	// Sends a result cmd with error information to indicate that a message processing failed
	ResultError(requestHeader *model.HeaderType, senderAddress *model.FeatureAddressType, err *model.ErrorType) error
	// Sends a reply cmd to response to a read cmd
	Reply(requestHeader *model.HeaderType, senderAddress *model.FeatureAddressType, cmd model.CmdType) error
	// Sends a call cmd with a subscription request
	Subscribe(senderAddress, destinationAddress *model.FeatureAddressType, serverFeatureType model.FeatureTypeType) (*model.MsgCounterType, error)
	// Sends a call cmd with a subscription delete request
	Unsubscribe(senderAddress, destinationAddress *model.FeatureAddressType) (*model.MsgCounterType, error)
	// Sends a call cmd with a binding request
	Bind(senderAddress, destinationAddress *model.FeatureAddressType, serverFeatureType model.FeatureTypeType) (*model.MsgCounterType, error)
	// Sends a call cmd with a binding delte request
	Unbind(senderAddress, destinationAddress *model.FeatureAddressType) (*model.MsgCounterType, error)
	// Sends a notify cmd to indicate that a subscribed feature changed
	Notify(senderAddress, destinationAddress *model.FeatureAddressType, cmd model.CmdType) (*model.MsgCounterType, error)
	// Sends a write cmd, setting properties of remote features
	Write(senderAddress, destinationAddress *model.FeatureAddressType, cmd model.CmdType) (*model.MsgCounterType, error)
	// return the datagram for a given msgCounter (only availbe for Notify messages!), error if not found
	DatagramForMsgCounter(msgCounter model.MsgCounterType) (model.DatagramType, error)
}

type SubscriptionEntry struct {
	Id            uint64
	ServerFeature FeatureLocalInterface
	ClientFeature FeatureRemoteInterface
}

type SubscriptionManagerInterface interface {
	AddSubscription(remoteDevice DeviceRemoteInterface, data model.SubscriptionManagementRequestCallType) error
	RemoveSubscription(data model.SubscriptionManagementDeleteCallType, remoteDevice DeviceRemoteInterface) error
	RemoveSubscriptionsForDevice(remoteDevice DeviceRemoteInterface)
	RemoveSubscriptionsForEntity(remoteEntity EntityRemoteInterface)
	Subscriptions(remoteDevice DeviceRemoteInterface) []*SubscriptionEntry
	SubscriptionsOnFeature(featureAddress model.FeatureAddressType) []*SubscriptionEntry
}

type WriteApprovalCallbackFunc func(msg *Message)