You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
587 lines
11 KiB
587 lines
11 KiB
=head1 NAME
|
|
|
|
PerlEz - PerlEz host DLL
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
This document attempts to describe the functions of the PerlEz host Dynamically
|
|
Linked Library (DLL). Please refer any questions or comments to the author below.
|
|
|
|
=head2 Datatypes
|
|
|
|
PerlEz has one specific data type, PERLEZHANDLE; this is a non-zero handle to
|
|
a Perl interpreter that is created and can be accessed by the routines described below.
|
|
|
|
=head2 PerlEzCreate
|
|
|
|
=over
|
|
|
|
PERLEZHANDLE PerlEzCreate(LPCSTR lpFileName, LPCSTR lpOptions);
|
|
|
|
=item DESCRIPTION:
|
|
|
|
=item *
|
|
|
|
Creates a Perl interpreter. The return value is required parameter for all subsequent ‘PerlEz’ calls.
|
|
Multiple interpreters can be created, but only one will be executing at a time.
|
|
|
|
=item PARAMS:
|
|
|
|
=item *
|
|
|
|
lpFileName a pointer to a ASCIIZ string that is the name of a file; can be NULL
|
|
|
|
=item *
|
|
|
|
lpOptions a pointer to a ASCIIZ string that are the command line options that
|
|
will be provided before the script; can be NULL. This parameter is used for setting @INC or debugging.
|
|
|
|
=item RETURNS:
|
|
|
|
=item *
|
|
|
|
A non zero handle to a Perl interpreter if successful; zero otherwise. Call PerlEzDelete to release this handle.
|
|
|
|
See also L</PerlEzDelete> L</PerlEzCreateOpt>
|
|
|
|
=back
|
|
|
|
=head2 PerlEzCreateOpt
|
|
|
|
=over
|
|
|
|
PERLEZHANDLE PerlEzCreateOpt(LPCSTR lpFileName, LPCSTR lpOptions, LPCSTR lpScriptOpts);
|
|
|
|
=item DESCRIPTION:
|
|
|
|
=item *
|
|
|
|
Creates a Perl interpreter. The return value is required parameter for all subsequent ‘PerlEz’ calls.
|
|
Multiple interpreters can be created, but only one will be executing at a time.
|
|
|
|
=item PARAMS:
|
|
|
|
=item *
|
|
|
|
lpFileName a pointer to a ASCIIZ string that is the name of a file; can be NULL
|
|
|
|
=item *
|
|
|
|
lpOptions a pointer to a ASCIIZ string that are the command line options that
|
|
will be provided before the script; can be NULL. This parameter is used for setting @INC or debugging.
|
|
|
|
=item *
|
|
|
|
lpScriptOpts a pointer to a ASCIIZ string that are the command line options that
|
|
will be provided as parameters to the script; can be NULL.
|
|
|
|
=item RETURNS:
|
|
|
|
=item *
|
|
|
|
A non zero handle to a Perl interpreter if successful; zero otherwise. Call PerlEzDelete to release this handle.
|
|
|
|
See also L</PerlEzDelete> L</PerlEzCreate>
|
|
|
|
=back
|
|
|
|
=head2 PerlEzDelete
|
|
|
|
=over
|
|
|
|
BOOL PerlEzDelete(PERLEZHANDLE hHandle);
|
|
|
|
=item DESCRIPTION:
|
|
|
|
=item *
|
|
|
|
Deletes a previously created Perl interpreter. Releases all resources allocated by PerlEzCreate or PerlEzCreateOpt.
|
|
|
|
=item PARAMS:
|
|
|
|
=item *
|
|
|
|
hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt
|
|
|
|
=item RETURNS:
|
|
|
|
=item *
|
|
|
|
True if no error false otherwise.
|
|
|
|
=back
|
|
|
|
=head2 PerlEzEvalString
|
|
|
|
=over
|
|
|
|
int PerlEzEvalString(PERLEZHANDLE hHandle, LPCSTR lpString, LPSTR lpBuffer, DWORD dwBufSize);
|
|
|
|
=item DESCRIPTION:
|
|
|
|
=item *
|
|
|
|
Evaluates the string a returns the result in lpBuffer. If there is an error $! is returned in lpBuffer.
|
|
|
|
=item PARAMS:
|
|
|
|
=item *
|
|
|
|
hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt
|
|
|
|
=item *
|
|
|
|
lpString a pointer to the ASCIIZ string to evaluate
|
|
|
|
=item *
|
|
|
|
lpBuffer a pointer to the buffer where the result will be placed
|
|
|
|
=item *
|
|
|
|
dwBufSize the size in bytes of the space where lpBuffer points
|
|
|
|
=item RETURNS:
|
|
|
|
=item *
|
|
|
|
A zero if no error; otherwise error code. See L</"Error Codes">
|
|
|
|
=back
|
|
|
|
=head2 PerlEzCall1
|
|
|
|
=over
|
|
|
|
int PerlEzCall1(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize, LPCSTR lpFormat, LPVOID lpVoid);
|
|
|
|
=item DESCRIPTION:
|
|
|
|
=item *
|
|
|
|
Calls the function lpFunction and returns the result in the buffer lpBuffer.
|
|
|
|
=item PARAMS:
|
|
|
|
=item *
|
|
|
|
hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt
|
|
|
|
=item *
|
|
|
|
lpFunction a pointer name of the function to call
|
|
|
|
=item *
|
|
|
|
lpBuffer a pointer to the buffer where the result will be placed
|
|
|
|
=item *
|
|
|
|
dwBufSize the size in bytes of the space where lpBuffer points
|
|
|
|
=item *
|
|
|
|
lpFormat a pointer to the parameter specifier; can be NULL. See L</"Format String">
|
|
|
|
=item *
|
|
|
|
lpVoid a pointer to a parameter will be interpreted based on lpFormat
|
|
|
|
=item RETURNS:
|
|
|
|
=item *
|
|
|
|
A zero if no error; otherwise error code. See L</"Error Codes">
|
|
|
|
=back
|
|
|
|
=head2 PerlEzCall2
|
|
|
|
=over
|
|
|
|
int PerlEzCall2(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
|
|
LPCSTR lpFormat, LPVOID lpVoid1, LPVOID lpVoid2);
|
|
|
|
=item DESCRIPTION:
|
|
|
|
=item *
|
|
|
|
Calls the function lpFunction and returns the result in the buffer lpBuffer.
|
|
|
|
=item PARAMS:
|
|
|
|
=item *
|
|
|
|
hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt
|
|
|
|
=item *
|
|
|
|
lpFunction a pointer name of the function to call
|
|
|
|
=item *
|
|
|
|
lpBuffer a pointer to the buffer where the result will be placed
|
|
|
|
=item *
|
|
|
|
dwBufSize the size in bytes of the space where lpBuffer points
|
|
|
|
=item *
|
|
|
|
lpFormat a pointer to the parameter specifier; can be NULL. See L</"Format String">
|
|
|
|
=item *
|
|
|
|
lpVoid1...2 pointers to parameters that will be interpreted based on lpFormat
|
|
|
|
=item RETURNS:
|
|
|
|
=item *
|
|
|
|
A zero if no error; otherwise error code. See L</"Error Codes">
|
|
|
|
=back
|
|
|
|
=head2 PerlEzCall4
|
|
|
|
=over
|
|
|
|
int PerlEzCall4(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
|
|
LPCSTR lpFormat, LPVOID lpVoid1, LPVOID lpVoid2, LPVOID lpVoid3, LPVOID lpVoid4);
|
|
|
|
=item DESCRIPTION:
|
|
|
|
=item *
|
|
|
|
Calls the function lpFunction and returns the result in the buffer lpBuffer.
|
|
|
|
=item PARAMS:
|
|
|
|
=item *
|
|
|
|
hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt
|
|
|
|
=item *
|
|
|
|
lpFunction a pointer name of the function to call
|
|
|
|
=item *
|
|
|
|
lpBuffer a pointer to the buffer where the result will be placed
|
|
|
|
=item *
|
|
|
|
dwBufSize the size in bytes of the space where lpBuffer points
|
|
|
|
=item *
|
|
|
|
lpFormat a pointer to the parameter specifier; can be NULL. See L</"Format String">
|
|
|
|
=item *
|
|
|
|
lpVoid1...4 pointers to parameters that will be interpreted based on lpFormat
|
|
|
|
=item RETURNS:
|
|
|
|
=item *
|
|
|
|
A zero if no error; otherwise error code. See L</"Error Codes">
|
|
|
|
=back
|
|
|
|
=head2 PerlEzCall8
|
|
|
|
=over
|
|
|
|
int PerlEzCall8(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
|
|
LPCSTR lpFormat, LPVOID lpVoid1, LPVOID lpVoid2, LPVOID lpVoid3, LPVOID lpVoid4, LPVOID lpVoid5,
|
|
LPVOID lpVoid6, LPVOID lpVoid7, LPVOID lpVoid8);
|
|
|
|
=item DESCRIPTION:
|
|
|
|
=item *
|
|
|
|
Calls the function lpFunction and returns the result in the buffer lpBuffer.
|
|
|
|
=item PARAMS:
|
|
|
|
=item *
|
|
|
|
hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt
|
|
|
|
=item *
|
|
|
|
lpFunction a pointer name of the function to call
|
|
|
|
=item *
|
|
|
|
lpBuffer a pointer to the buffer where the result will be placed
|
|
|
|
=item *
|
|
|
|
dwBufSize the size in bytes of the space where lpBuffer points
|
|
|
|
=item *
|
|
|
|
lpFormat a pointer to the parameter specifier; can be NULL. See L</"Format String">
|
|
|
|
=item *
|
|
|
|
lpVoid1...8 pointers to parameters that will be interpreted based on lpFormat
|
|
|
|
=item RETURNS:
|
|
|
|
=item *
|
|
|
|
A zero if no error; otherwise error code. See L</"Error Codes">
|
|
|
|
=back
|
|
|
|
=head2 PerlEzCall
|
|
|
|
=over
|
|
|
|
int PerlEzCall(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPSTR lpBuffer, DWORD dwBufSize,
|
|
LPCSTR lpFormat, ...);
|
|
|
|
=item DESCRIPTION:
|
|
|
|
=item *
|
|
|
|
Calls the function lpFunction and returns the result in the buffer lpBuffer.
|
|
|
|
=item PARAMS:
|
|
|
|
=item *
|
|
|
|
hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt
|
|
|
|
=item *
|
|
|
|
lpFunction a pointer name of the function to call
|
|
|
|
=item *
|
|
|
|
lpBuffer a pointer to the buffer where the result will be placed
|
|
|
|
=item *
|
|
|
|
dwBufSize the size in bytes of the space where lpBuffer points
|
|
|
|
=item *
|
|
|
|
lpFormat a pointer to the parameter specifier; can be NULL. See L</"Format String">
|
|
|
|
=item *
|
|
|
|
... parameters to be interpreted based on lpFormat
|
|
|
|
=item RETURNS:
|
|
|
|
=item *
|
|
|
|
A zero if no error; otherwise error code. See L</"Error Codes">
|
|
|
|
=back
|
|
|
|
=head2 PerlEzCallContext
|
|
|
|
=over
|
|
|
|
int PerlEzCallContext(PERLEZHANDLE hHandle, LPCSTR lpFunction, LPVOID lpContextInfo,
|
|
LPSTR lpBuffer, DWORD dwBufSize, LPCSTR lpFormat, ...);
|
|
|
|
=item DESCRIPTION:
|
|
|
|
=item *
|
|
|
|
Calls the function lpFunction and returns the result in the buffer lpBuffer.
|
|
|
|
=item PARAMS:
|
|
|
|
=item *
|
|
|
|
hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt
|
|
|
|
=item *
|
|
|
|
lpFunction a pointer name of the function to call
|
|
|
|
=item *
|
|
|
|
lpContextInfo context info for magic fetch and store functions
|
|
|
|
=item *
|
|
|
|
lpBuffer a pointer to the buffer where the result will be placed
|
|
|
|
=item *
|
|
|
|
dwBufSize the size in bytes of the space where lpBuffer points
|
|
|
|
=item *
|
|
|
|
lpFormat a pointer to the parameter specifier; can be NULL. See L</"Format String">
|
|
|
|
=item *
|
|
|
|
... parameters to be interpreted based on lpFormat
|
|
|
|
=item RETURNS:
|
|
|
|
=item *
|
|
|
|
A zero if no error; otherwise error code. See L</"Error Codes">
|
|
|
|
=back
|
|
|
|
=head2 PerlEzSetMagicScalarFunctions
|
|
|
|
=over
|
|
|
|
int PerlEzSetMagicScalarFunctions(PERLEZHANDLE hHandle, LPFETCHVALUEFUNCTION lpfFetch,
|
|
LPSTOREVALUEFUNCTION lpfStore);
|
|
|
|
=item DESCRIPTION:
|
|
|
|
=item *
|
|
|
|
Sets the call back function pointers for magic scalar variables.
|
|
|
|
=item PARAMS:
|
|
|
|
=item *
|
|
|
|
hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt
|
|
|
|
=item *
|
|
|
|
lpfFetch a pointer to the call back function for fetching a string.
|
|
if lpfFetch is NULL, then the scalar is write only.
|
|
|
|
=item *
|
|
|
|
lpfStore a pointer to the call back function for storinging a string.
|
|
if lpfStore is NULL, then the scalar is read only.
|
|
|
|
=item RETURNS:
|
|
|
|
=item *
|
|
|
|
A zero if no error; otherwise error code. See L</"Error Codes">
|
|
NOTE: if lpfFetch and lpfStore are both NULL, then it is an error.
|
|
|
|
See also L</PerlEzSetMagicScalarName>
|
|
|
|
=back
|
|
|
|
=head2 PerlEzSetMagicScalarName
|
|
|
|
=over
|
|
|
|
int PerlEzSetMagicScalarName(PERLEZHANDLE hHandle, LPCSTR pVariableName);
|
|
|
|
=item DESCRIPTION:
|
|
|
|
=item *
|
|
|
|
Creates the variable if it does not exists and sets it to be tied to
|
|
the call back function pointer for magic variables.
|
|
|
|
=item PARAMS:
|
|
|
|
=item *
|
|
|
|
hHandle a handle returned by the call to PerlEzCreate or PerlEzCreateOpt
|
|
|
|
=item *
|
|
|
|
pVariableName a pointer to the name of the variable.
|
|
|
|
=item RETURNS:
|
|
|
|
=item *
|
|
|
|
A zero if no error; otherwise error code. See L</"Error Codes">
|
|
|
|
See also L</PerlEzSetMagicScalarFunctions>
|
|
|
|
=back
|
|
|
|
=head2 Format String
|
|
|
|
=over
|
|
|
|
The format string is a series of characters that represents the type of parameters being supplied.
|
|
|
|
=item s
|
|
|
|
=item *
|
|
|
|
this parameter is a pointer to a null terminated string.
|
|
|
|
=item i
|
|
|
|
=item *
|
|
|
|
this parameter is to be considered an integer.
|
|
|
|
=item d
|
|
|
|
=item *
|
|
|
|
this parameter is to be considered a double.
|
|
|
|
=item l[s | i | d]x
|
|
|
|
=item *
|
|
|
|
the next 'x' parameters will be put into an anonymous list of the type specifed. Either 's', 'i', or 'd'
|
|
|
|
=back
|
|
|
|
=head2 Error Codes
|
|
|
|
=over
|
|
|
|
=item 1
|
|
|
|
More space is needed to return a result
|
|
|
|
=item 2
|
|
|
|
Error string returned in the buffer
|
|
|
|
=item 3
|
|
|
|
More space needed to return the error message
|
|
|
|
=item 4
|
|
|
|
Format string is invalid
|
|
|
|
=item 5
|
|
|
|
Function call caused an exception
|
|
|
|
=item 6
|
|
|
|
Handle is invalid
|
|
|
|
=item 7
|
|
|
|
The second call to PerlEzSetMagicFunction failed
|
|
|
|
=item 8
|
|
|
|
Invalid parameter was passed to the routine
|
|
|
|
=item 9
|
|
|
|
Cannot allocate more memory
|
|
|
|
=back
|
|
|
|
=head1 AUTHORS
|
|
|
|
This document is maintained by Douglas Lankshear <[email protected]>
|