github.com/enbility/spine-go@v0.7.0/api/feature.go (about)

     1  package api
     2  
     3  import (
     4  	"time"
     5  
     6  	"github.com/enbility/spine-go/model"
     7  )
     8  
     9  /* Feature */
    10  
    11  // This interface defines the functions being common to local and remote features
    12  // A feature corresponds to a SPINE feature, see SPINE Introduction Chapter 2.2
    13  type FeatureInterface interface {
    14  	// Get the feature address
    15  	Address() *model.FeatureAddressType
    16  	// Get the feature type
    17  	Type() model.FeatureTypeType
    18  	// Get the feature role
    19  	Role() model.RoleType
    20  	// Get the feature operations
    21  	Operations() map[model.FunctionType]OperationsInterface
    22  	// Get the feature description
    23  	Description() *model.DescriptionType
    24  	// Set the feature description with a given type
    25  	SetDescription(desc *model.DescriptionType)
    26  	// Set the feature description with a given string
    27  	SetDescriptionString(s string)
    28  	// Return a descriptive feature summary as a string
    29  	String() string
    30  }
    31  
    32  // Callback function used to verify if an incoming SPINE write message should be allowed or not
    33  // The cb function has to be invoked within 1 minute, otherwise the stack will
    34  // deny the write command
    35  type WriteApprovalCallbackFunc func(msg *Message)
    36  
    37  // This interface defines all the required functions need to implement a local feature
    38  type FeatureLocalInterface interface {
    39  	FeatureInterface
    40  	// Get the associated DeviceLocalInterface implementation
    41  	Device() DeviceLocalInterface
    42  	// Get the associated EntityLocalInterface implementation
    43  	Entity() EntityLocalInterface
    44  
    45  	// Add a function type with allowed operations
    46  	AddFunctionType(function model.FunctionType, read, write bool)
    47  	// Add a callback function to be invoked when SPINE message comes in with a given msgCounterReference value
    48  	//
    49  	// Returns an error if there is already a callback for the msgCounter set
    50  	AddResponseCallback(msgCounterReference model.MsgCounterType, function func(msg ResponseMessage)) error
    51  	// Add a callback function to be invoked when a result message comes in for this feature
    52  	AddResultCallback(function func(msg ResponseMessage))
    53  
    54  	// Add a callback method for a server feature which is invoked to
    55  	// check wether an incoming write message shall be approved or denied
    56  	AddWriteApprovalCallback(function WriteApprovalCallbackFunc) error
    57  	// This function needs to be invoked within (default) 10 seconds after the via
    58  	// AddWriteApprovalCallback defined callback is being invoked.
    59  	//
    60  	// NOTE: To approve a write, ALL callbacks need to approve the write!
    61  	//
    62  	// ErrorType.ErrorNumber should be 0 if write is approved
    63  	ApproveOrDenyWrite(msg *Message, err model.ErrorType)
    64  	// Overwrite the default 1 minute timeout for write approvals
    65  	SetWriteApprovalTimeout(duration time.Duration)
    66  
    67  	// Clean all write approval caches for a remote device ski
    68  	CleanWriteApprovalCaches(ski string)
    69  	// Clean all remote device specific caches
    70  	CleanRemoteDeviceCaches(remoteAddress *model.DeviceAddressType)
    71  	// Clean all remote entity specific caches
    72  	CleanRemoteEntityCaches(remoteAddress *model.EntityAddressType)
    73  
    74  	// return all functions
    75  	Functions() []model.FunctionType
    76  
    77  	// Get a copy of the features data for a given function type
    78  	DataCopy(function model.FunctionType) any
    79  	// Update the features data for a given function type
    80  	UpdateData(function model.FunctionType, data any, filterPartial *model.FilterType, filterDelete *model.FilterType) *model.ErrorType
    81  	// Set the features data for a given function type
    82  	SetData(function model.FunctionType, data any)
    83  
    84  	// Trigger a read request message for a given FeatureRemoteInterface implementation
    85  	RequestRemoteData(
    86  		function model.FunctionType,
    87  		selector any,
    88  		elements any,
    89  		destination FeatureRemoteInterface) (*model.MsgCounterType, *model.ErrorType)
    90  	// Trigger a read request message for a remote ski and feature address
    91  	RequestRemoteDataBySenderAddress(
    92  		cmd model.CmdType,
    93  		sender SenderInterface,
    94  		destinationSki string,
    95  		destinationAddress *model.FeatureAddressType,
    96  		maxDelay time.Duration) (*model.MsgCounterType, *model.ErrorType)
    97  
    98  	// Check if there already is a subscription to a given feature remote address
    99  	HasSubscriptionToRemote(remoteAddress *model.FeatureAddressType) bool
   100  	// Trigger a subscription request to a given feature remote address
   101  	SubscribeToRemote(remoteAddress *model.FeatureAddressType) (*model.MsgCounterType, *model.ErrorType)
   102  	// Trigger a subscription removal request for a given feature remote address
   103  	RemoveRemoteSubscription(remoteAddress *model.FeatureAddressType) (*model.MsgCounterType, *model.ErrorType)
   104  	// Trigger subscription removal requests for all subscriptions of this feature
   105  	RemoveAllRemoteSubscriptions()
   106  
   107  	// Check if there already is a binding to a given feature remote address
   108  	HasBindingToRemote(remoteAddress *model.FeatureAddressType) bool
   109  	// Trigger a binding request to a given feature remote address
   110  	BindToRemote(remoteAddress *model.FeatureAddressType) (*model.MsgCounterType, *model.ErrorType)
   111  	// Trigger a binding removal request for a given feature remote address
   112  	RemoveRemoteBinding(remoteAddress *model.FeatureAddressType) (*model.MsgCounterType, *model.ErrorType)
   113  	// Trigger binding removal requests for all subscriptions of this feature
   114  	RemoveAllRemoteBindings()
   115  
   116  	// Handle an incoming SPINE message for this feature
   117  	HandleMessage(message *Message) *model.ErrorType
   118  
   119  	// Get the SPINE data structure for NodeManagementDetailDiscoveryData messages for this feature
   120  	Information() *model.NodeManagementDetailedDiscoveryFeatureInformationType
   121  }
   122  
   123  // Interface for local NodeManagement feature
   124  type NodeManagementInterface interface {
   125  	FeatureLocalInterface
   126  }
   127  
   128  // This interface defines all the required functions need to implement a remote feature
   129  type FeatureRemoteInterface interface {
   130  	FeatureInterface
   131  
   132  	// Get the associated DeviceRemoteInterface implementation
   133  	Device() DeviceRemoteInterface
   134  	// Get the associated EntityRemoteInterface implementation
   135  	Entity() EntityRemoteInterface
   136  
   137  	// Get a copy of the features data for a given function type
   138  	DataCopy(function model.FunctionType) any
   139  	// Set the features data for a given function type
   140  	// persist true will store the data, false will return the updated data without storing it
   141  	UpdateData(persist bool, function model.FunctionType, data any, filterPartial *model.FilterType, filterDelete *model.FilterType) (any, *model.ErrorType)
   142  
   143  	// Set the supported operations of the feature for a set of functions
   144  	SetOperations(functions []model.FunctionPropertyType)
   145  
   146  	// Define the maximum response duration
   147  	SetMaxResponseDelay(delay *model.MaxResponseDelayType)
   148  	// Get the maximum allowed response duration
   149  	MaxResponseDelayDuration() time.Duration
   150  }