507 lines
9.4 KiB
Plaintext
507 lines
9.4 KiB
Plaintext
=head1 NAME
|
||
|
||
PerlEz - PerlEz host DLL
|
||
|
||
=head1 DESCRIPTION
|
||
|
||
This document attempts to describe the functions of the PerlEz host Dynamicly
|
||
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, LPSTR 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>
|
||
|
||
=back
|
||
|
||
=head2 PerlEzDelete
|
||
|
||
=over
|
||
|
||
BOOL PerlEzDelete(PERLEZHANDLE hHandle);
|
||
|
||
=item DESCRIPTION:
|
||
|
||
=item *
|
||
|
||
Deletes a previously created Perl interpreter. Releases all resources allocated by PerlEzCreate.
|
||
|
||
=item PARAMS:
|
||
|
||
=item *
|
||
|
||
hHandle a handle returned by the call to PerlEzCreate
|
||
|
||
=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
|
||
|
||
=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.
|
||
|
||
=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
|
||
|
||
=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.
|
||
|
||
=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
|
||
|
||
=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.
|
||
|
||
=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
|
||
|
||
=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.
|
||
|
||
=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
|
||
|
||
=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.
|
||
|
||
=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
|
||
|
||
=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.
|
||
|
||
=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
|
||
|
||
=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.
|
||
|
||
=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
|
||
|
||
=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.
|
||
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.
|
||
|
||
=item *
|
||
|
||
pVariableName a pointer to the name of the variable.
|
||
|
||
=item RETURNS:
|
||
|
||
=item *
|
||
|
||
A zero if no error; otherwise error code.
|
||
|
||
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
|
||
|
||
=head1 AUTHORS
|
||
|
||
This document is maintained by Douglas Lankshear <dougl@ActiveState.com>
|