Studio:Function.pm

Description

This package provides a better impedence match for perl when making STRIDE function calls (via ascript). It maps standard perl data structures (scalars, arrays, and hashes) into the corresponding STRIDE ascript payload elements. Furthermore, all of the functions in the current database are AUTOLOADed into this class, so they dynamically become members of this package. The ascript Constants (preprocessor macros) are also dynamically loaded. These features allow users to use make function calls via this package using a more natural perl syntax.

This library is considered an alpha-level release since it does not support all payload types that are available in the STRIDE Communication Language.

Example

Source:

typedef struct {
    int first;
    double second;
    unsigned int third;
    char fourth;
} MyStruct;
 
typedef struct {
    int first;
    double second;
    unsigned int third;
    char fourth;
} ReturnData;
 
#define MY_TYPE 2
 
int MyFun_1 (int foo, unsinged int type, char baz);
int MyFun_2 (int foo, MyStruct bar, double baz);
ReturnData MyFun_3(void ** pHandle); 
    
#pragma scl_function(MyFun_1)
#pragma scl_function(MyFun_2)
#pragma scl_function(MyFun_3)
#pragma scl_ptr(MyFun3.pHandle,OUT,PRIVATE)

Script:

use strict;
use Win32::TieRegistry(Delimiter=>"/");
use File::Spec;
use Win32::OLE;
Win32::OLE->Option(Warn => 3);
   
use vars qw($StrideDirectory $StrideLibDirectory);
   
BEGIN {
    $StrideDirectory = $Registry->{"LMachine/SOFTWARE/S2 Technologies/STRIDE/InstallDir"};
    $StrideLibDirectory = File::Spec->catdir($StrideDirectory, 'lib', 'perl');  
}
use lib $StrideLibDirectory;
use S2S::Function;
   
my $caller = new S2S::Function();
my $retval = $caller->MyFun_1(1, $caller->MY_TYPE, 3);
    
$retval = $caller->MyFun_2(1, {first=>2, second=>3, third=>4, fourth=>5}, 6);
    
my $pHandle;
my $hashRef = $caller->MyFun_3(\$pHandle);

Methods

new ('ascript' => object, 'database' => 'database path')

Creates an instance of a Function object. The constructor will, by default, look in the main namespace for a scalar value called 'ascript' and initialize itself with that object. If, however, this constructor is called with an 'ascript' or 'database' named argument (hash-style argument syntax), then it will use one of these provided values to initialize the ascript instance.

database

read/write property. Setting this will effectively reinitialize the database for the Function instance.

ascript

read/write property. Setting this will effectively reinitialize the database for the Function instance.

async

read/write property that determines whether the underlying ascript call is made with Call() (synchronous) or CallNonBlocking() (asynchronous). This property is false by default.

constants

This is a reference to a tied hash that gives read only access to the preprocessor constants in the database. Although the constants are AUTOLOADed into the class, you can use this member to explicitly access the constants collection (either for iteration or in cases where a function name conflicts with a constant name).

AUTOLOADed methods

All functions and constants in the current database are AUTOLOADed by default and available for use. For functions, The calling syntax uses perl native data structures and the library attempts to map those types to the correct payload members internally. In the case where a function and a constant exist in the database with exactly the same name, preference is given to the function call when AUTOLOADing. If you know you want to access the constant value, you can access the 'constants' hashref member directly. Currently only simple input and output payloads are supported - namely simple scalars, strings, structs, and pointers (partial). Arrays, Unions, and Enums are not currently supported, but will be in future versions. Outpointers are mapped to input arguments, but the positional arguments that correspond must be provided by reference.