UNPKG

tc-context

Version:

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

720 lines 27.6 kB
/** * Module, which contains the definitions of all support TwinCAT Types, from which `TcSymbols` can be instantiated * * * 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 */ /// <reference types="node" /> /// <reference types="debug" /> import { TcContext } from './tc-context'; import { TcSymbol } from './tc-symbol'; import { TcTypeInfo, TcEnumBuffers, TcArrayDimension, TcTypeBase, TcSymbolPointer } from './tc-com'; /** * Base class for a TwinCAT Type, designed to store the basic information of the Type, as well as provide options * for cloning itself, and extending with additional attributes. * * Types can be mutated with attributes, which allow for altered behavior. */ export declare abstract class TcType { /** * Creates the base for a TwinCAT Data type. Can be build either from raw ADS Type Info, or from * an existing `TcType` * * @param context - The `TcContext`, to which this Type belongs * @param typeData - The information, from which the `TcType` is build * @param debug - If enabled, will produce debug information */ protected constructor(context: TcContext, typeData: TcTypeInfo | TcType, debug?: boolean); /** * The default value for this `TcType` */ get defaultValue(): any; set defaultValue(val: any); /** * Flag, if this `TcType` is ignored during Symbol Building */ get ignored(): boolean; set ignored(val: boolean); /** * The {@link ADST} Type ID */ get adst(): number; /** * The memory offset, relative to its parent, if the `TcType` is a child */ get offset(): number; set offset(val: number); /** * Size of the Target PLC Type */ get size(): number; set size(val: number); /** * If a default value is present, the default byte buffer of that value */ get defaultBuffer(): Buffer | undefined; set defaultBuffer(val: Buffer | undefined); /** * Flag, if this `TcType` is ReadOnly */ get readOnly(): boolean; set readOnly(val: boolean); /** * The Target PLC Type name */ get name(): string; /** * The `TcContext`, which this `TcType` is part of */ get context(): TcContext; /** * Alias to use, in place of the default 'set' event, when * a `TcSymbol` of this type is constructed */ get onSet(): string; set onSet(val: string); /** * Alias to use, in place of the default 'get' event, when * a `TcSymbol` of this type is constructed */ get onGet(): string; set onGet(val: string); /** * Alias to use, in place of the default 'cleared' event, when * a `TcSymbol` of this type is constructed */ get onClear(): string; set onClear(val: string); /** * Alias to use, in place of the default 'changed' event, when * a `TcSymbol` of this type is constructed */ get onChange(): string; set onChange(val: string); /** * Clones this `TcType` and mutates it, with additional attributes from * the mutator * * @param mutator - Will use the Attributes and Offset to create a mutation of this `TcType` */ mutate(mutator: TcTypeBase): void; /** * Extends the current `TcType` with the provided `TcTypeInfo`. The default extension * can either create a mutation of the current `TcType` or transform the `TcType` into * an array * * @param adsTypeData - Data with which to extends the `TcType` * * @return - Either the extends `TcType` or `undefined` if extension failed */ extend(adsTypeData: TcTypeInfo): Promise<TcType | undefined>; /** * Will create a `TcSymbol` instance based on this `TcType` * * @param path - Path of the created `TcSymbol` * @param parent - Parent of the created `TcSymbol` * @param pointer - Memory location of created `TcSymbol` in the Target PLC * @param debug - If enabled, will produce debug information * * @return - Instance of `TcSymbol` based on this `TcType` */ abstract instance(path: string, parent: TcSymbol, pointer: TcSymbolPointer, debug: boolean): TcSymbol; /** * Creates a clone with an optional mutation of this `TcType` * * @param mutator - Optional mutator, which can be applied to the clone * * @throws {@link TcComIsInvalidException} - Attempting to use an invalidated `TcCom` Object * @throws {@link TcComToRawException} - Error occurred when transforming value to raw data * * @return - Either the clone `TcType` or `undefined` if cloning failed */ abstract clone(mutator?: TcTypeBase): Promise<TcType | undefined>; /** * Internal function for applying mutations to the created clone. * Used for code reduction * * @param type - the TcType, which can be potentially mutated * @param mutator - The mutator which can be applied to the `TcType` * * @throws {@link TcComIsInvalidException} - Attempting to use an invalidated `TcCom` Object * @throws {@link TcComToRawException} - Error occurred when transforming value to raw data * * @return - Either the clone `TcType` or `undefined` if cloning failed */ protected __clone(type: TcType, mutator?: TcTypeBase): Promise<TcType | undefined>; /** * Internal function, which analyses attribute data from the Type ADS Data and * adjusts aspects of this `TcType` * * Mutations supported : * - ReadOnly * - Ignored * - OnSet * - OnGet * - OnClear * - OnChange * * @param name - name of the Attribute * @param value - value of the Attribute */ protected __getParameter(name: string, value: string): void; /** * @internal */ private __readOnly; /** * @internal */ private __ignored; /** * @internal */ private __name; /** * @internal */ private __adst; /** * @internal */ private __context; /** * @internal */ private __offset; /** * @internal */ private __size; /** * @internal */ protected __default: any; /** * @internal */ private __defaultBuffer?; /** * @internal */ private __onSet?; /** * @internal */ private __onGet?; /** * @internal */ private __onClear?; /** * @internal */ private __onChange?; /** * @internal */ protected __log: debug.Debugger; } /** * Class representing a `BOOL` Type in the Target PLC. */ export declare class TcBooleanType extends TcType { /** * Constructs a `TcBooleanType` to represent a `BOOL` Type in the Target PLC * * @param context - The `TcContext`, to which this Type belongs * @param typeData - The information, from which the `TcType` is build * @param debug - If enabled, will produce debug information */ protected constructor(context: TcContext, typeData: TcTypeInfo | TcBooleanType, debug?: boolean); /** * Creates an instance of `TcBooleanType` with default values transformed to * raw data * * @param context - The `TcContext`, to which this Type belongs * @param typeData - The information, from which the `TcType` is build * @param debug - If enabled, will produce debug information * * @throws {@link TcComIsInvalidException} - Attempting to use an invalidated `TcCom` Object * @throws {@link TcComToRawException} - Error occurred when transforming value to raw data * * @return - An initialized instance of `TcBooleanType` if it is not ignored */ static create(context: TcContext, typeData: TcTypeInfo | TcBooleanType, debug?: boolean): Promise<TcBooleanType | undefined>; /** * Default value for a `BOOL` if it is not explicitly specified */ get defaultValue(): boolean; /** * Creates an instance of a Type `BOOL` PLC Symbol, based on this `TcType` * * @param path - Path of the created `TcSymbol` * @param parent - Parent of the created `TcSymbol` * @param pointer - Memory location of created `TcSymbol` in the Target PLC * @param debug - If enabled, will produce debug information * * @return - An `TcSymbol` instance of a Symbol of type `BOOL` */ instance(path: string, parent: TcSymbol, pointer: TcSymbolPointer, debug?: boolean): TcSymbol; /** * Creates a clone with an optional mutation of this `TcType` * * @param mutator - Optional mutator, which can be applied to the clone * * @throws {@link TcComIsInvalidException} - Attempting to use an invalidated `TcCom` Object * @throws {@link TcComToRawException} - Error occurred when transforming value to raw data * * @return - Either the clone `TcType` or `undefined` if cloning failed */ clone(mutator?: TcTypeBase): Promise<TcType | undefined>; /** * Internal function, which analyses attribute data from the Type ADS Data and * adjusts aspects of this `TcType` * * Mutations supported : * - ReadOnly * - Ignored * - OnSet * - OnGet * - OnClear * - OnChange * - Default * * @param name - name of the Attribute * @param value - value of the Attribute */ protected __getParameter(name: string, value: string): void; } /** * Class representing all numeric Types in the Target PLC */ export declare class TcNumericType extends TcType { /** * Default Ranges for all the Numeric Types possible in a TwinCAT PLC. * If not explicitly specified, will be used for `upperBorder` and `lowerBorder` * definitions */ static ranges: { [key: number]: { min: number | bigint; max: number | bigint; }; }; /** * Constructs a `TcNumericType` to represent all numeric Types in the Target PLC * * @param context - The `TcContext`, to which this Type belongs * @param typeData - The information, from which the `TcType` is build * @param debug - If enabled, will produce debug information */ protected constructor(context: TcContext, typeData: TcTypeInfo | TcNumericType, debug?: boolean); /** * Creates an instance of `TcNumericType` with default values transformed to * raw data * * @param context - The `TcContext`, to which this Type belongs * @param typeData - The information, from which the `TcType` is build * @param debug - If enabled, will produce debug information * * @throws {@link TcComIsInvalidException} - Attempting to use an invalidated `TcCom` Object * @throws {@link TcComToRawException} - Error occurred when transforming value to raw data * * @return - An initialized instance of `TcNumericType` if it is not ignored */ static create(context: TcContext, typeData: TcTypeInfo | TcNumericType, debug?: boolean): Promise<TcNumericType | undefined>; /** * Default value for a `BOOL` if it is not explicitly specified */ get defaultValue(): number | bigint; /** * Maximum value of this Numeric Type */ get upperBorder(): number | bigint; set upperBorder(val: number | bigint); /** * Minimum value of this Numeric Type */ get lowerBorder(): number | bigint; set lowerBorder(val: number | bigint); /** * Creates an instance of a numeric Type PLC Symbol, based on this `TcType * * @param path - Path of the created `TcSymbol` * @param parent - Parent of the created `TcSymbol` * @param pointer - Memory location of created `TcSymbol` in the Target PLC * @param debug - If enabled, will produce debug information * * @return - An `TcSymbol` instance of a Symbol of a numeric type */ instance(path: string, parent: TcSymbol, pointer: TcSymbolPointer, debug?: boolean): TcSymbol; /** * Extends the current `TcType` with the provided `TcTypeInfo`. Can be extended either to * an array of `TcNumericType` or `TcEnumType`. Otherwise, creates a mutate clone * * @param adsTypeData - Data with which to extends the `TcType` * * @return - Either the extends `TcType` or `undefined` if extension failed */ extend(adsTypeData: TcTypeInfo): Promise<TcType | undefined>; /** * Creates a clone with an optional mutation of this `TcType` * * @param mutator - Optional mutator, which can be applied to the clone * * @throws {@link TcComIsInvalidException} - Attempting to use an invalidated `TcCom` Object * @throws {@link TcComToRawException} - Error occurred when transforming value to raw data * * @return - Either the clone `TcType` or `undefined` if cloning failed */ clone(mutator?: TcTypeBase): Promise<TcType | undefined>; /** * Internal function, which analyses attribute data from the Type ADS Data and * adjusts aspects of this `TcType` * * Mutations supported : * - ReadOnly * - Ignored * - OnSet * - OnGet * - OnClear * - OnChange * - Default * - UpperBorder * - LowerBorder * * @param name - name of the Attribute * @param value - value of the Attribute */ protected __getParameter(name: string, value: string): void; /** * @internal */ private __upperBorder; /** * @internal */ private __lowerBorder; } /** * Class representing a `STRING` or `WSTRING` Type in the Target PLC. */ export declare class TcStringType extends TcType { /** * Constructs a `TcStringType` to represent a `STRING` or `WSTRING` Type in the Target PLC * * @param context - The `TcContext`, to which this Type belongs * @param typeData - The information, from which the `TcType` is build * @param debug - If enabled, will produce debug information */ protected constructor(context: TcContext, typeData: TcTypeInfo | TcStringType, debug?: boolean); /** * Creates an instance of `TcStringType` with default values transformed to * raw data * * @param context - The `TcContext`, to which this Type belongs * @param typeData - The information, from which the `TcType` is build * @param debug - If enabled, will produce debug information * * @throws {@link TcComIsInvalidException} - Attempting to use an invalidated `TcCom` Object * @throws {@link TcComToRawException} - Error occurred when transforming value to raw data * * @return - An initialized instance of `TcStringType` if it is not ignored */ static create(context: TcContext, typeData: TcTypeInfo | TcStringType, debug?: boolean): Promise<TcStringType | undefined>; /** * The maximum length of a string, which can be stored in this Type */ get length(): number; set length(val: number); /** * Default value for a `STRING` or `WSTRING` if it is not explicitly specified */ get defaultValue(): any; /** * Creates an instance of Type `STRING` or `WSTRING` PLC Symbol, based on this `TcType` * * @param path - Path of the created `TcSymbol` * @param parent - Parent of the created `TcSymbol` * @param pointer - Memory location of created `TcSymbol` in the Target PLC * @param debug - If enabled, will produce debug information * * @return - An `TcSymbol` instance of a Symbol of type `STRING` or `WSTRING` */ instance(path: string, parent: TcSymbol, pointer: TcSymbolPointer, debug?: boolean): TcSymbol; /** * Creates a clone with an optional mutation of this `TcType` * * @param mutator - Optional mutator, which can be applied to the clone * * @throws {@link TcComIsInvalidException} - Attempting to use an invalidated `TcCom` Object * @throws {@link TcComToRawException} - Error occurred when transforming value to raw data * * @return - Either the clone `TcType` or `undefined` if cloning failed */ clone(mutator?: TcTypeBase): Promise<TcType | undefined>; /** * Internal function, which analyses attribute data from the Type ADS Data and * adjusts aspects of this `TcType` * * Mutations supported : * - ReadOnly * - Ignored * - OnSet * - OnGet * - OnClear * - OnChange * - Default * * @param name - name of the Attribute * @param value - value of the Attribute */ protected __getParameter(name: string, value: string): void; /** * @internal */ private __length; } /** * Class representing all `ENUM` Types in the Target PLC */ export declare class TcEnumType extends TcType { /** * Constructs a `TcEnumType` to represent a `ENUM` Type in the Target PLC * * @param context - The `TcContext`, to which this Type belongs * @param typeData - The information, from which the `TcType` is build * @param debug - If enabled, will produce debug information */ protected constructor(context: TcContext, typeData: TcTypeInfo | TcEnumType, debug?: boolean); /** * Creates an instance of `TcEnumType` with default values transformed to * raw data * * @param context - The `TcContext`, to which this Type belongs * @param typeData - The information, from which the `TcType` is build * @param debug - If enabled, will produce debug information * * @throws {@link TcComIsInvalidException} - Attempting to use an invalidated `TcCom` Object * @throws {@link TcComToRawException} - Error occurred when transforming value to raw data * * @return - An initialized instance of `TcEnumType` if it is not ignored */ static create(context: TcContext, typeData: TcTypeInfo | TcEnumType, debug?: boolean): Promise<TcEnumType | undefined>; /** * Access all the fields, which are allowed to be written * to this `ENUM` */ get fields(): string[]; set fields(val: string[]); /** * Access all the data buffers, which represent the `ENUM` fields */ get buffers(): TcEnumBuffers; set buffers(val: TcEnumBuffers); /** * Creates an instance of Type `ENUM` PLC Symbol, based on this `TcType` * * @param path - Path of the created `TcSymbol` * @param parent - Parent of the created `TcSymbol` * @param pointer - Memory location of created `TcSymbol` in the Target PLC * @param debug - If enabled, will produce debug information * * @return - An `TcSymbol` instance of a Symbol of type `ENUM` */ instance(path: string, parent: TcSymbol, pointer: TcSymbolPointer, debug?: boolean): TcSymbol; /** * Creates a clone with an optional mutation of this `TcType` * * @param mutator - Optional mutator, which can be applied to the clone * * @throws {@link TcComIsInvalidException} - Attempting to use an invalidated `TcCom` Object * @throws {@link TcComToRawException} - Error occurred when transforming value to raw data * * @return - Either the clone `TcType` or `undefined` if cloning failed */ clone(mutator?: TcTypeBase): Promise<TcType | undefined>; /** * Internal function, which analyses attribute data from the Type ADS Data and * adjusts aspects of this `TcType` * * Mutations supported : * - ReadOnly * - Ignored * - OnSet * - OnGet * - OnClear * - OnChange * - Default * * @param name - name of the Attribute * @param value - value of the Attribute */ protected __getParameter(name: string, value: string): void; /** * @internal */ private __enumFields; /** * @internal */ private __enumBuffers; } /** * Class representing a `Structures`, `Function_Blocks` and `Unions` Types in the Target PLC. */ export declare class TcStructType extends TcType { /** * Constructs a `TcBooleanType` to represent `Structures`, `Function_Blocks` and `Unions` Types in the Target PLC * * @param context - The `TcContext`, to which this Type belongs * @param typeData - The information, from which the `TcType` is build * @param children - The Children Types, that are part of this structure * @param debug - If enabled, will produce debug information */ protected constructor(context: TcContext, typeData: TcTypeInfo | TcStructType, children?: { key: string; type: TcType; }[], debug?: boolean); /** * Creates an instance of `TcStructType` * * @param context - The `TcContext`, to which this Type belongs * @param typeData - The information, from which the `TcType` is build * @param children - The Children Types, that are part of this structure * @param debug - If enabled, will produce debug information * * @throws {@link TcComIsInvalidException} - Attempting to use an invalidated `TcCom` Object * @throws {@link TcComToRawException} - Error occurred when transforming value to raw data * * @return - An initialized instance of `TcStructType` if it is not ignored */ static create(context: TcContext, typeData: TcTypeInfo | TcStructType, children?: { key: string; type: TcType; }[], debug?: boolean): Promise<TcStructType | undefined>; /** * Children and their types of this structure */ get children(): { key: string; type: TcType; }[]; /** * List of all RPC Methods available for this structure */ get rpcMethods(): string[]; /** * Creates an instance of Type `Structure`, `Function_Block` or `Union` PLC Symbol, based on this `TcType` * * @param path - Path of the created `TcSymbol` * @param parent - Parent of the created `TcSymbol` * @param pointer - Memory location of created `TcSymbol` in the Target PLC * @param debug - If enabled, will produce debug information * * @return - An `TcSymbol` instance of a Symbol of type `Structures`, `Function_Blocks` or `Union` */ instance(path: string, parent: TcSymbol, pointer: TcSymbolPointer, debug?: boolean): TcSymbol; /** * Creates a clone with an optional mutation of this `TcType` * * @param mutator - Optional mutator, which can be applied to the clone * * @throws {@link TcComIsInvalidException} - Attempting to use an invalidated `TcCom` Object * @throws {@link TcComToRawException} - Error occurred when transforming value to raw data * * @return - Either the clone `TcType` or `undefined` if cloning failed */ clone(mutator?: TcTypeBase): Promise<TcType | undefined>; /** * @internal */ private __children; /** * @internal */ private __rpcMethods; } /** * Class representing an `ARRAY` Type in the Target PLC. */ export declare class TcArrayType extends TcType { /** * Constructs a `TcArrayType` to represent an `ARRAY` Type in the Target PLC * * @param context - The `TcContext`, to which this Type belongs * @param typeData - The information, from which the `TcType` is build * @param child - The type of the Array to create * @param debug - If enabled, will produce debug information */ protected constructor(context: TcContext, typeData: TcTypeInfo | TcArrayType, child: TcType, debug?: boolean); /** * Creates an instance of `TcArrayType` * * @param context - The `TcContext`, to which this Type belongs * @param typeData - The information, from which the `TcType` is build * @param child - The type of the Array to create * @param debug - If enabled, will produce debug information * * @throws {@link TcComIsInvalidException} - Attempting to use an invalidated `TcCom` Object * @throws {@link TcComToRawException} - Error occurred when transforming value to raw data * * @return - An initialized instance of `TcArrayType` if it is not ignored */ static create(context: TcContext, typeData: TcTypeInfo | TcArrayType, child: TcType, debug?: boolean): Promise<TcArrayType | undefined>; /** * Access the Dimensions of array */ get dimensions(): TcArrayDimension[]; set dimensions(val: TcArrayDimension[]); /** * The Child `TcType` of this Array */ get child(): TcType; /** * Creates a clone with an optional mutation of this `TcType` * * @param mutator - Optional mutator, which can be applied to the clone * * @throws {@link TcComIsInvalidException} - Attempting to use an invalidated `TcCom` Object * @throws {@link TcComToRawException} - Error occurred when transforming value to raw data * * @return - Either the clone `TcType` or `undefined` if cloning failed */ clone(mutator?: TcTypeBase): Promise<TcType | undefined>; /** * Creates an instance of a Type `ARRAY` PLC Symbol, based on this `TcType` * * @param path - Path of the created `TcSymbol` * @param parent - Parent of the created `TcSymbol` * @param pointer - Memory location of created `TcSymbol` in the Target PLC * @param debug - If enabled, will produce debug information * * @return - An `TcSymbol` instance of a Symbol of type `ARRAY` */ instance(path: string, parent: TcSymbol, pointer: TcSymbolPointer, debug?: boolean): TcSymbol; /** * @internal */ private __child; /** * @internal */ private __dimensions; } //# sourceMappingURL=tc-type.d.ts.map