tc-context/dist/tc-context.d.ts

TwinCAT ADS Communication Library for creating an active TwinCAT Context, with automatic symbol and type mapping

/**
 * Module containing the main TcContext Class, responsible for establishing connection over TwinCAT's ADS layer,
 * generating the Type and Symbol Maps for future communication.
 *
 *
 * Licensed under MIT License.
 *
 * Copyright (c) 2020 Dmitrij Trifanov <d.v.trifanov@gmail.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 * IN THE SOFTWARE.
 *
 * @packageDocumentation
 */
import { TcCom, TcComSettings } from './tc-com';
import { TcTypeRegistry } from './tc-type-registry';
import { TcSymbolRegistry } from './tc-symbol-registry';
import * as TcEvents from './tc-event';
import { TcNamespaceSymbol } from './tc-symbol';
/**
 * Class responsible for creating the connection, mapping the types and symbols over the TwinCAT's ADS
 * layer. Its purpose is to serve as the entry point for the tc-context Library.
 *
 * Creation of a context is done through the `TcContext.create()` static method, due to the asynchronous
 * nature of creation.
 *
 * ```js
 * const { TcContext } = require('tc-context');
 *
 * TcContext.create().then(context => {
 *     //.....
 *     await context.kill();
 * })
 * ```
 *
 */
export declare class TcContext extends TcEvents.TcEmitter {
    /**
     * Internal constructor, which creates and binds all the Components of `TcContext`, used by `TcContext.create()`
     *
     * @param settings - Settings used for communicating over ADS. Definition of connection settings can be found at [ads-client](https://github.com/jisotalo/ads-client) library
     * @param onSourceChange - Callback which is issued when Code Change is detected. If none is specified, the the `TcContext.reinitialize` function is bound to it
     * @param debug - If enabled, all components of `TcContext` will produce debug information
     */
    private constructor();
    /**
     * Function responsible for the creation of `TcContext`, as well as initializing all of its components
     *
     * ```js
     * const { TcContext } = require('tc-context');
     *
     * TcContext.create().then(context => {
     *     //.....
     * })
     * ```
     * @param settings - Settings used for communicating over ADS. Definition of connection settings can be found at [ads-client](https://github.com/jisotalo/ads-client) library
     * @param onSourceChange - Callback which is issued when Code Change is detected. If none is specified, the the `TcContext.reinitialize` function is bound to it
     * @param debug - If enabled, all components of `TcContext` will produce debug information
     *
     * @throws {@link TcComBusyException} - Connection is already created and `TcCom` is busy
     * @throws {@link TcComConnectException} - Failure establishing ADS Communication
     * @throws {@link TcComChangeDetectionException} - Failure enabling Code Change monitoring
     * @throws {@link TcComTypeQueryException} - Failure querying Type Data from TwinCAT
     * @throws {@link TcComSymbolQueryException} - Failure querying Symbol Data from TwinCAT
     * @throws {@link TcComIsInvalidException} - Attempting to use an Invalidated TcCom Object
     *
     * @return - The newly created, connected and mapped `TcContext`
     */
    static create(settings: TcComSettings, onSourceChange?: () => void, debug?: boolean): Promise<TcContext>;
    /**
     * Function responsible for explicitly killing `TcContext`, rendering it unusable, unless `TcContext.reinitialize()` is called
     * afterwards, which will reconnect and rebuild a new `TcContext` with previously passed settings
     *
     * ```js
     * const { TcContext } = require('tc-context');
     *
     * TcContext.create().then(context => {
     *
     *     await context.kill()
     *     //context is no longer usable afterwards
     *
     * })
     * ```
     * ***NOTE:*** Even if the function throws an exception, the context will still be rendered unusable
     *
     * @throws {@link TcComUnsubscribeException} - Failure unsubscribing from TwinCAT Symbol
     * @throws {@link TcComDisconnectException} - Failure disconnecting from ADS Target
     *
     * @return - The killed `TcContext`, which is no longer usable
     */
    kill(): Promise<TcContext>;
    /**
     * Function, which using the previously passed settings during `TcContext.create()` call, will kill the `TcContext`
     * and then reconnect and rebuild all the components.
     *
     * This function is automatically called, whenever the `TcCom` module detects a code change on the PLC if
     * no explicit callback was given during construction
     *
     * @throws {@link TcComBusyException} - Connection is already created and `TcCom` is busy
     * @throws {@link TcComConnectException} - Failure establishing ADS Communication
     * @throws {@link TcComChangeDetectionException} - Failure enabling Code Change monitoring
     * @throws {@link TcComTypeQueryException} - Failure querying Type Data from TwinCAT
     * @throws {@link TcComSymbolQueryException} - Failure querying Symbol Data from TwinCAT
     * @throws {@link TcComIsInvalidException} - Attempting to use an Invalidated TcCom Object
     * @throws {@link TcComUnsubscribeException} - Failure unsubscribing from TwinCAT Symbol
     * @throws {@link TcComDisconnectException} - Failure disconnecting from ADS Target
     * @throws {@link TcComToRawException} - Error occurred when transforming value to raw data
     *
     * @return - The reinitialized `TcContext`
     */
    reinitialize(): Promise<TcContext>;
    /**
     * Access to the ADS Communication Module, through which all ADS Actions are made
     */
    get COM(): TcCom;
    /**
     * Access to the Registry, which stores all the TwinCAT Type Data, pulled from the PLC, and which
     * is used for Symbol generation
     */
    get types(): TcTypeRegistry;
    /**
     * Access to the Registry, which stores the Symbol Map, generated based on the TwinCAT PLC Data and the
     * Type data gathered by the `TcContext.types` Component
     */
    get symbols(): TcSymbolRegistry;
    /**
     * Shortcut operator of `TcContext.symbols.namespaces`, for quickly accessing the created `TcNamespaces`
     */
    get $(): {
        [key: string]: TcNamespaceSymbol;
    };
    /**
     * Emitted when `TcContext` is killed and is no longer usable
     * @event killed
     */
    on(event: 'killed', listener: (e: TcEvents.TcContextKilledEvent) => void): any;
    /**
     * Emitted when `TcContext` is reinitialized
     * @event reinitialized
     */
    on(event: 'reinitialized', listener: (e: TcEvents.TcContextReinitializedEvent) => void): any;
    /**
     * Emitted from {@link TcCom} when it establishes a connection to the PLC
     * @event connected
     */
    on(event: 'connected', listener: (e: TcEvents.TcComConnectedEvent) => void): any;
    /**
     * Emitted from {@link TcCom} when it disconnects from the PLC
     * @event disconnected
     */
    on(event: 'disconnected', listener: (e: TcEvents.TcComDisconnectedEvent) => void): any;
    /**
     * Emitted from {@link TcCom} when it detect Code Changes in the PLC
     * @event sourceChanged
     */
    on(event: 'sourceChanged', listener: (e: TcEvents.TcComSourceChangedEvent) => void): any;
    /**
     * Emitted from {@link TcSymbolRegistry} when it creates the Symbol Map
     * @event created
     */
    on(event: 'created', listener: (e: TcEvents.TcSymbolRegistryCreatedEvent) => void): any;
    /**
     * Emitted from {@link TcSymbolRegistry} when it destroys the Symbol Map
     * @event destroyed
     */
    on(event: 'destroyed', listener: (e: TcEvents.TcSymbolRegistryDestroyedEvent) => void): any;
    /**
     * Emitted from {@link TcTypeRegistry} when it creates the Type Map
     * @event created
     */
    on(event: 'created', listener: (e: TcEvents.TcTypeRegistryCreatedEvent) => void): any;
    /**
     * Emitted from {@link TcTypeRegistry} when it destroys the Types Map
     * @event destroyed
     */
    on(event: 'destroyed', listener: (e: TcEvents.TcTypeRegistryDestroyedEvent) => void): any;
    /**
     * Emitted from {@link TcBinding} of a {@link TcSymbol} when `TcSymbol.$set()` has completed
     * @event set
     */
    on(event: 'set', listener: (e: TcEvents.TcSymbolSetEvent) => void): any;
    /**
     * Emitted from {@link TcBinding} of a {@link TcSymbol} when `TcSymbol.$get` has completed
     * @event get
     */
    on(event: 'get', listener: (e: TcEvents.TcSymbolGetEvent) => void): any;
    /**
     * Emitted from {@link TcBinding} of a {@link TcSymbol} when `TcSymbol.$clear()` has completed
     * @event cleared
     */
    on(event: 'cleared', listener: (e: TcEvents.TcSymbolClearedEvent) => void): any;
    /**
     * Emitted from {@link TcBinding} of a {@link TcSymbol} when `TcSymbol` detects a change in the PLC Symbol
     * @event changed
     */
    on(event: 'changed', listener: (e: TcEvents.TcSymbolChangedEvent) => void): any;
    /**
     * Internal function used by `TcContext.create()` static method, to initialize all the Components of the `TcContext` Object
     *
     * @throws {@link TcComBusyException} - Connection is already created and `TcCom` is busy
     * @throws {@link TcComConnectException} - Failure establishing ADS Communication
     * @throws {@link TcComChangeDetectionException} - Failure enabling Code Change monitoring
     * @throws {@link TcComTypeQueryException} - Failure querying Type Data from TwinCAT
     * @throws {@link TcComSymbolQueryException} - Failure querying Symbol Data from TwinCAT
     * @throws {@link TcComIsInvalidException} - Attempting to use an Invalidated TcCom Object
     * @throws {@link TcComToRawException} - Error occurred when transforming value to raw data
     *
     * @return - The newly created, connected and mapped `TcContext`
     *
     */
    private __initialize;
    /**
     * ADS Communication Module
     * @internal
     */
    private __com;
    /**
     * Will register all the TwinCAT Types, which will be used by `TcSymbolRegistry` to create Symbol Map
     * @internal
     */
    private __types;
    /**
    * Will created and store the TwinCAT Symbol Map
    * @internal
    */
    private __symbols;
    /**
     * @internal
     */
    private __log;
}
//# sourceMappingURL=tc-context.d.ts.map