spi

Documentation

Overview

Package spi is meant for internal plc4x driver development. !!!Attention this is an SPI (Service Provider Interfaces). These SPIs can change at any time. Only use them if you really know what you are doing!!!

  _______________________________________
< You read this text and understood it? >
 ---------------------------------------
                       \                    ^    /^
                        \                  / \  // \
                         \   |\___/|      /   \//  .\
                          \  /O  O  \__  /    //  | \ \           *----*
                            /     /  \/_/    //   |  \  \          \   |
                            @___@`    \/_   //    |   \   \         \/\ \
                           0/0/|       \/_ //     |    \    \         \  \
                       0/0/0/0/|        \///      |     \     \       |  |
                    0/0/0/0/0/_|_ /   (  //       |      \     _\     |  /
                 0/0/0/0/0/0/`/,_ _ _/  ) ; -.    |    _ _\.-~       /   /
                             ,-}        _      *-.|.-~-.           .~    ~
            \     \__/        `/\      /                 ~-. _ .-~      /
             \____(oo)           *.   }            {                   /
             (    (--)          .----~-.\        \-`                 .~
             //__\\  \__ Ack!   ///.----..<        \             _ -~
            //    \\               ///-._ _ _ _ _ _ _{^ - - - - ~

Index

• type AcceptsMessage
• type CompletableFuture
• type CompletionFuture
• type Expectation
• type HandleError
• type HandleMessage
• type HandlerExposer
• type Message
• type MessageCodec
• type PlcBrowser
• type PlcDiscoverer
• type PlcReader
• type PlcSubscriber
• type PlcTagHandler
• type PlcValueHandler
• type PlcWriter
• type TransportAware
• type TransportInstanceExposer

Types

type AcceptsMessage

type AcceptsMessage func(message Message) bool

AcceptsMessage If this function returns true, the message is forwarded to the message handler

type CompletableFuture

type CompletableFuture[T any] interface {
	// Complete If not already completed, sets the value returned by get()
	// and related methods to the given value.
	Complete(value T)
	// CompleteWithError If not already completed, causes invocations of get()
	// and related methods to return the given error.
	CompleteWithError(err error)
	// Cancel If not already completed, complete this CompletableFuture with
	// a CancellationError
	Cancel()

	// IsDone Returns true if completed in any fashion: normally, exceptionally,
	// or via cancellation.
	IsDone() bool
	// IsCancelled Returns true if this CompletableFuture was cancelled before
	// it completed normally.
	IsCancelled() bool
	// IsCompletedWithError Returns true if this CompletableFuture completed
	// with an error, in any way (Cancelled or completed with error).
	IsCompletedWithError() bool

	// Get Waits if necessary for this future to complete, and then returns its
	// result.
	Get() T
	// GetWithTimeout Waits if necessary for at most the given time for this
	// future to complete, and then returns its result, if available.
	GetWithTimeout(timeout time.Duration) T
	// GetNow Returns the result value (or throws any encountered exception)
	// if completed, else returns the given valueIfAbsent.
	GetNow(valueIfAbsent T) T
	// WhenComplete When this CompletableFuture completes either normally or
	// exceptionally, it passes this CompletableFutures result and error as
	// arguments to the supplied function.
	WhenComplete(func(value T, err error))
	// HandleAsync When this CompletableFuture completes either normally or
	// exceptionally, it passes this CompletableFutures result and error as
	// arguments to the supplied function.
	HandleAsync(func(value T, err error))
	// ThenApply When this CompletableFuture completes normally, it passes its
	// result as the argument to the supplied function.
	ThenApply(func(value T))
}

type CompletionFuture

type CompletionFuture interface {
	pool.CompletionFuture
}

Deprecated: don't use it in productive code

type Expectation

type Expectation interface {
	fmt.Stringer
	GetContext() context.Context
	GetCreationTime() time.Time
	GetExpiration() time.Time
	GetAcceptsMessage() AcceptsMessage
	GetHandleMessage() HandleMessage
	GetHandleError() HandleError
}

type HandleError

type HandleError func(err error) error

HandleError Function for handling the message, returns an error if anything goes wrong

type HandleMessage

type HandleMessage func(message Message) error

HandleMessage Function for handling the message, returns an error if anything goes wrong

type HandlerExposer

type HandlerExposer interface {
	// GetPlcTagHandler returns the PlcTagHandler
	GetPlcTagHandler() PlcTagHandler
	// GetPlcValueHandler returns the PlcValueHandler
	GetPlcValueHandler() PlcValueHandler
}

HandlerExposer exposes PlcTagHandler and PlcValueHandler

type Message

type Message interface {
	fmt.Stringer
	utils.Serializable
	utils.LengthAware
}

type MessageCodec

type MessageCodec interface {
	// Deprecated: use ConnectWithContext
	// Connect connects this codec
	Connect() error
	// ConnectWithContext connects this codec with the supplied context
	ConnectWithContext(ctx context.Context) error
	// Disconnect disconnects this codec
	Disconnect() error
	// IsRunning returns true if the codec (workers are running)
	IsRunning() bool

	// Send is sending a given message
	Send(message Message) error
	// Expect Wait for a given timespan for a message to come in, which returns 'true' for 'acceptMessage'
	// and is then forwarded to the 'handleMessage' function
	Expect(ctx context.Context, acceptsMessage AcceptsMessage, handleMessage HandleMessage, handleError HandleError, ttl time.Duration) error
	// SendRequest A combination that sends a message first and then waits for a response. !!!Important note: the callbacks are blocking calls
	SendRequest(ctx context.Context, message Message, acceptsMessage AcceptsMessage, handleMessage HandleMessage, handleError HandleError, ttl time.Duration) error

	// GetDefaultIncomingMessageChannel gives back the chan where unexpected messages arrive
	GetDefaultIncomingMessageChannel() chan Message
}

MessageCodec handles sending and retrieving of messages

type PlcBrowser

type PlcBrowser interface {
	// Browse Non-Blocking request, which will return a full result as soon as the operation is finished
	Browse(ctx context.Context, browseRequest apiModel.PlcBrowseRequest) <-chan apiModel.PlcBrowseRequestResult

	// BrowseWithInterceptor Variant of the Browser, which allows immediately intercepting found resources
	// This is ideal, if additional information has to be queried on such found resources
	// and especially for connection-based protocols can reduce the stress on the system
	// and increase throughput. It can also be used for simple filtering.
	// If the interceptor function returns 'true' the result is added to the overall result
	// if it's 'false' is is not.
	BrowseWithInterceptor(ctx context.Context, browseRequest apiModel.PlcBrowseRequest, interceptor func(result apiModel.PlcBrowseItem) bool) <-chan apiModel.PlcBrowseRequestResult
}

PlcBrowser defines an interface to browse PLCs

type PlcDiscoverer

type PlcDiscoverer interface {
	// Discover discovers PLCs according to discoveryOptions and calls callback on every discovery
	Discover(callback func(event apiModel.PlcDiscoveryItem), discoveryOptions ...options.WithDiscoveryOption) error
	// DiscoverWithContext discovers PLCs according to discoveryOptions and calls callback on every discovery
	DiscoverWithContext(ctx context.Context, callback func(event apiModel.PlcDiscoveryItem), discoveryOptions ...options.WithDiscoveryOption) error
}

PlcDiscoverer defines an interface to discover PLCs

type PlcReader

type PlcReader interface {
	// Read reads a field from a PLC
	Read(ctx context.Context, readRequest apiModel.PlcReadRequest) <-chan apiModel.PlcReadRequestResult
}

PlcReader reads fields form a PLC

type PlcSubscriber

type PlcSubscriber interface {
	// Subscribe subscribes to fields of a PLC
	Subscribe(ctx context.Context, subscriptionRequest apiModel.PlcSubscriptionRequest) <-chan apiModel.PlcSubscriptionRequestResult
	// Unsubscribe removes subscriptions
	Unsubscribe(ctx context.Context, unsubscriptionRequest apiModel.PlcUnsubscriptionRequest) <-chan apiModel.PlcUnsubscriptionRequestResult
	// Register registers a callback for a model.PlcSubscriptionHandle
	Register(consumer apiModel.PlcSubscriptionEventConsumer, handles []apiModel.PlcSubscriptionHandle) apiModel.PlcConsumerRegistration
	// Unregister removes a model.PlcSubscriptionHandle
	Unregister(registration apiModel.PlcConsumerRegistration)
}

PlcSubscriber handles subscriptions to a PLC

type PlcTagHandler

type PlcTagHandler interface {
	// ParseTag Parser function to parse tag address strings for a given driver and produce PlcTag instances from that
	ParseTag(tagAddress string) (apiModel.PlcTag, error)
	// ParseQuery Parser function to parse query strings for a given driver and produce PlcTag instances from that
	ParseQuery(query string) (apiModel.PlcQuery, error)
}

PlcTagHandler provides apiModel.PlcTag and apiModel.PlcQuery related methods

type PlcValueHandler

type PlcValueHandler interface {
	// NewPlcValue creates a apiValues.NewPlcValue for a supplied apiModel.PlcTag
	NewPlcValue(tag apiModel.PlcTag, value any) (apiValues.PlcValue, error)
}

PlcValueHandler provides functionality for apiValues.PlcValue

type PlcWriter

type PlcWriter interface {
	// Write writes a field to a PLC
	Write(ctx context.Context, writeRequest apiModel.PlcWriteRequest) <-chan apiModel.PlcWriteRequestResult
}

PlcWriter writes fields to a PLC

type TransportAware

type TransportAware interface {
	// RegisterTransport Manually register a new driver
	RegisterTransport(transport transports.Transport)
	// ListTransportNames List the names of all drivers registered in the system
	ListTransportNames() []string
	// GetTransport Get access to a driver instance for a given driver-name
	GetTransport(transportName string, connectionString string, options map[string][]string) (transports.Transport, error)
}

TransportAware exposes transports.Transport related functionality

type TransportInstanceExposer

type TransportInstanceExposer interface {
	// GetTransportInstance returns a transports.TransportInstance
	GetTransportInstance() transports.TransportInstance
}

TransportInstanceExposer exposes the transports.TransportInstance