tc-context
Version:
TwinCAT ADS Communication Library for creating an active TwinCAT Context, with automatic symbol and type mapping
720 lines • 27.6 kB
TypeScript
/**
* 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