About
Windows Scripting for Autohotkey (stdlib) v0.21 beta
Requires Autohotkey v1.0.47 or above.
Home page: http://www.autohotkey.net/~easycom/
These internal functions shouldn't normally be used except by ws4ahk itself, but are documented here for completeness (and in the case someone wants to play around with the inner workings of the module).
License
Copyright (c) 2007,2008 erictheturtle of AutoHotKey forums
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.
Description
Sets ErrorLevel with the last ScriptError.Description.
Usage
__WS_HandleScriptError()
Return Value
None ("").
ErrorLevel
The ScriptError.Description text, or if there is no text, a default automation error message with number.
Remarks
Also clears the last script error.
Related
WS_Exec, WS_Eval
Description
Create COM object directly from a DLL or OCX file.
Usage
WS_CreateObjectFromDll(sDllPath, sClassID [, sInterfaceID = IDispatch ] )
Parameters
Return Value
ErrorLevel
Remarks
To create a COM object, it must be registered with the system. This function skips the standard approach and creates objects directly from the DLL or OCX file. Since this involves a bit of hackery, it is not guaranteed to work. This has been tested with msscript.ocx and seems to work without any problems.
This is a port of the code from the very clever Elias on The Code Project. http://www.codeproject.com/com/Emul_CoCreateInstance.asp
Related
WS_CreateObject, WS_ReleaseObject
Example
#Include ws4ahk.ahk
WS_Initialize()
; Create the Microsoft Scripting Control directly from the DLL
pScriptCtrl := WS_CreateObjectFromDll("C:\Windows\system32\msscript.ocx"
,"{0E59F1D5-1FBE-11D0-8FF2-00A0D10038BC}"
,"{0E59F1D3-1FBE-11D0-8FF2-00A0D10038BC}")
WS_AddObject(pScriptCtrl, "oScript")
WS_Exec("oScript.Language = %s", "VBScript")
WS_Exec("oScript.ExecuteStatement %s", "Msgbox ""Did this blow your mind?""")
Description
Manually creates an object by directly accessing the DLL/OCX file.
Usage
__WS_CreateInstanceFromDll(sDllPath, ByRef sBinaryClassID, ByRef sBinaryIId)
Parameters
Return Value
ErrorLevel
Remarks
This involves a bit of hackery, but it usually seems to work. This isn't the recommended way of creating objects, so use at your own risk.
This code is based on the amazing work by Elias (aka lallous) on CodeProject.
http://www.codeproject.com/com/Emul_CoCreateInstance.asp
Note that there is no need to free the library explicitly. It should be automatically freed when CoUninitialize is called.
Used in WS_CreateObjectFromDll
Related
Description
Try to query a COM object for the 'most useful' interface.
Usage
__WS_GetIDispatch(pIDispatch [, iLocaleID = Default ] )
Parameters
Return Value
ErrorLevel
Remarks
I don't quite understand the purpose of doing this, but Sean was doing it, and the code found here http://svn.python.org/projects/ctypes/trunk/comtypes/comtypes/client/__init__.py was doing it, so I guess this can do it too.
Related
WS_CreateObject, WS_GetObject, WS_CreateObjectFromDll
Description
Looks up the binary Class ID of a Program ID.
Usage
__WS_CLSIDFromProgID(sProgID, ByRef BinaryClassID)
Parameters
Return Value
(Boolean) True on success, False on failure.
ErrorLevel
Remarks
The binary ClassId is stored in a string that must be passed ByRef because returning AHK strings 'by value' that contain binary data will be truncated to the first 0x00 binary value.
Related
__WS_CLSIDFromString, __WS_IIDFromString
Description
Converts a string Class ID to a binary Class ID.
Usage
__WS_CLSIDFromString(sClassID, ByRef BinaryClassID)
Parameters
Return Value
(Boolean) True on success, False on failure.
ErrorLevel
Remarks
The binary ClassId is stored in a string that must be passed ByRef because returning AHK strings 'by value' that contain binary data will be truncated to the first 0x00 binary value.
Related
__WS_CLSIDFromProgID, __WS_IIDFromString
Description
Converts a string Interface ID to a binary Interface ID.
Usage
__WS_IIDFromString(sIId, ByRef BinaryIId)
Parameters
Return Value
(Boolean) True on success, False on failure.
ErrorLevel
Remarks
The binary Interface ID is stored in a string that must be passed ByRef because returning AHK strings 'by value' that contain binary data will be tuncated to the first 0x00 binary value.
Win API function IIDFromString() seems to be identical to Win API function CLSIDFromString(). I really don't see why there are two separate functions to do this.
Related
__WS_CLSIDFromProgID, __WS_CLSIDFromString
Description
Checks for error and sets ErrorLevel.
Usage
__WS_IsComError(sFunctionName, iHRESULT)
Parameters
Return Value
(Boolean) True if there is an error. False if HRESULT indicates success (HRESULT >= 0).
ErrorLevel
0 if previous DllCall was successful and HRESULT = 0 (S_OK). Error description if was an error, or a success message.
Remarks
Should be called right after a DllCall(). Checks ErrorLevel for DllCall() error, then checks HRESULT for success or failure.
Related
Description
Sets ErrorLevel with an error.
Usage
__WS_ComError(?Error, sDescription)
Parameters
Return Value
None ("").
ErrorLevel
Set with a formatted error message.
Remarks
Related
Description
Converts an ANSI string to its UTF16 equivalent.
Usage
__WS_ANSI2Unicode(sAnsiString, ByRef Utf16String)
Parameters
Return Value
(Boolean) True on success, False on failure.
ErrorLevel
Remarks
Returned string must be ByRef because passing AHK strings 'by value' that contain binary data will be truncated to the first 0x00 binary value.
Related
Description
Converts a UTF16 string to its ANSI equivalent.
Usage
__WS_Unicode2ANSI(psUtf16, ByRef Ansi)
Parameters
Return Value
(Boolean) True on success, False on failure.
ErrorLevel
Not changed.
Remarks
Related
Description
Get pointer to the function at the specified vtable index.
Usage
__WS_VTable(pVTable, iIndex)
Parameters
Return Value
(Integer) Pointer to the desired function.
ErrorLevel
Not changed.
Remarks
Related
Description
Converts a string to a BSTR.
Usage
__WS_StringToBSTR(sAnsi)
Parameters
Return Value
ErrorLevel
Remarks
Converts a normal ANSI string to Unicode, then creates a BSTR with it. The resulting BSTR should be freed with the __WS_FreeBSTR function.
Related
Description
Frees a BSTR.
Usage
__WS_FreeBSTR(pBSTR)
Parameters
Return Value
DllCall() result.
ErrorLevel
Not changed.
Remarks
Related
Description
Converts a VARIANT structure to a normal AHK variable.
Usage
__WS_UnpackVARIANT(ByRef sVARIANT, ByRef RetVal)
Parameters
Return Value
(Boolean) True on success, False on failure.
ErrorLevel
Not changed.
Remarks
Most return types are handled. Unhandled types are:
Related
Description
Releases references and clears the contents of a VARIANT structure.
Usage
__WS_VariantClear(ByRef sVARIANT)
Parameters
Return Value
(Boolean) True on success, False on failure.
ErrorLevel
Remarks
Related
VTable
0 call_QueryInterface - Returns a pointer to a specified interface on an object to which a client currently holds an interface pointer
1 call_AddRef - Increments the reference count for an interface on an object
2 call_Release - Decrements the reference count for the calling interface on a object
3 call_GetTypeInfoCount - Retrieves the number of type information interfaces that an object provides (either 0 or 1)
4 call_GetTypeInfo - Retrieves the type information for an object
5 call_GetIDsOfNames - Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs
6 call_Invoke - Provides access to properties and methods exposed by an object.
7 * get_Language - Language engine to use
8 * put_Language - Language engine to use
9 get_State - State of the control
10 put_State - State of the control
11 * put_SitehWnd - hWnd used as a parent for displaying UI
12 * get_SitehWnd - hWnd used as a parent for displaying UI
13 get_Timeout - Length of time in milliseconds that a script can execute before being considered hung
14 put_Timeout - Length of time in milliseconds that a script can execute before being considered hung
15 * get_AllowUI - Enable or disable display of the UI
16 * put_AllowUI - Enable or disable display of the UI
17 get_UseSafeSubset - Force script to execute in safe mode and disallow potentially harmful actions
18 put_UseSafeSubset - Force script to execute in safe mode and disallow potentially harmful actions
19 get_Modules - Collection of modules for the ScriptControl
20 * get_Error - The last error reported by the scripting engine
21 get_CodeObject - Object exposed by the scripting engine that contains methods and properties defined in the code added to the global module
22 get_Procedures - Collection of procedures that are defined in the global module
23 call__AboutBox -
24 * call_AddObject - Add an object to the global namespace of the scripting engine
25 call_Reset - Reset the scripting engine to a newly created state
26 call_AddCode - Add code to the global module
27 * call_Eval - Evaluate an expression within the context of the global module
28 * call_ExecuteStatement - Execute a statement within the context of the global module
29 call_Run - Call a procedure defined in the global module
(only the * members are implemented)
Description
Gets/Sets the language engine to use.
Usage
__WS_IScriptControl_Language(pIScriptControl [, sLanguage] )
Parameters
Return Value
If Language argument is supplied:
If Language argument is NOT supplied:
ErrorLevel
Remarks
Changing the scripting language seems to reset the environment.
If language has not been set, returns "".
It is possible that languages other than VBScript and JScript could be set/returned. These alternate scripting languages would have be properly registered with the system (but I've never seen any language that can do that).
Related
Description
Get/set hWnd used as a parent for displaying UI.
Usage
__WS_IScriptControl_SitehWnd(pIScriptControl [, iWindowHandle] )
Parameters
Return Value
If WindowHandle argument is supplied:
If WindowHandle argument is NOT supplied:
ErrorLevel
Remarks
Related
Description
Gets/sets if the display of the UI is enabled or disabled.
Usage
__WS_IScriptControl_AllowUI(pIScriptControl [, blnAllow] )
Parameters
Return Value
If blnAllow argument is provided:
If blnAllow argument is NOT provided:
ErrorLevel
Remarks
Related
Description
Gets the error object used by the scripting engine.
Usage
__WS_IScriptControl_Error(pIScriptControl)
Parameters
Return Value
ErrorLevel
Remarks
Related
Description
Add an object to the global namespace of the scripting engine.
Usage
__WS_IScriptControl_AddObject(pIScriptControl, sObjName, pIObjDispatch, blnAddMembers)
Parameters
Return Value
(Boolean) True on success, False on failure.
ErrorLevel
Remarks
If blnAddMembers is True, all members of the object become publicly accessable identifiers.
Related
Description
Evaluate an expression within the context of the global module.
Usage
__WS_IScriptControl_Eval(pIScriptControl, sExpression, ByRef VarRet)
Parameters
Return Value
ErrorLevel
Remarks
On success, VarRet will be set with the evaluation result.
On failure, it will be a 16 byte empty string.
Like __WS_IScriptControl_ExecuteStatement, this function does not process the HRESULT. The HRESULT is returned so that further handling can be performed.
Related
IScriptControl, __WS_IScriptControl_ExecuteStatement
Description
Execute a statement within the context of the global module.
Usage
__WS_IScriptControl_ExecuteStatement(pIScriptControl, sCode)
Parameters
Return Value
ErrorLevel
Remarks
Like __WS_IScriptControl_Eval, this function does not process the HRESULT. The HRESULT is returned so that further handling can be performed.
Related
IScriptControl, __WS_IScriptControl_Eval
VTable
0 call_QueryInterface - Returns a pointer to a specified interface on an object to which a client currently holds an interface pointer
1 call_AddRef - Increments the reference count for an interface on an object
2 call_Release - Decrements the reference count for the calling interface on a object
3 call_GetTypeInfoCount - Retrieves the number of type information interfaces that an object provides (either 0 or 1)
4 call_GetTypeInfo - Retrieves the type information for an object
5 call_GetIDsOfNames - Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs
6 call_Invoke - Provides access to properties and methods exposed by an object.
7 * get_Number - Error number
8 get_Source - Source of the error
9 * get_Description - Friendly description of error
10 get_HelpFile - File in which help for the error can be found
11 get_HelpContext - Context ID for the topic with information on the error
12 get_Text - Line of source code on which the error occurred
13 get_Line - Source code line number where the error occurred
14 get_Column - Source code column position where the error occurred
15 * call_Clear - Clear the script error
(only the * members are implemented)
Description
Get the last error number.
Usage
__WS_IScriptError_Number(pIScriptError)
Parameters
Return Value
ErrorLevel
Remarks
Related
Description
Get a friendly description of the last error.
Usage
__WS_IScriptError_Description(pIScriptError)
Parameters
Return Value
ErrorLevel
Remarks
Related
Description
Clear the script error.
Usage
__WS_IScriptError_Clear(pIScriptError)
Parameters
Return Value
(Boolean) True on success, False on failure.
ErrorLevel
Remarks
Related
VTable
0 call_QueryInterface Returns a pointer to a specified interface on an object to which a client currently holds an interface pointer 1 call_AddRef Increments the reference count for an interface on an object 2 call_Release Decrements the reference count for the calling interface on a object 3 * call_CreateInstance Creates an uninitialized object. 4 call_LockServer Locks object application open in memory. (only the * members are implemented)
Description
Creates an uninitialized object.
Usage
__WS_IClassFactory_CreateInstance(pIClassFactory)
Parameters
Return Value
ErrorLevel
Remarks
Used in __WS_CreateInstanceFromDll() function.
Related
VTable
0 call_QueryInterface Returns pointers to supported interfaces.
1 call_AddRef Increments reference count.
2 call_Release Decrements reference count.
3 * call_GetTypeAttr Retrieves a TYPEATTR structure that contains the attributes of the type description.
4 call_GetTypeComp Retrieves the ITypeComp interface for the type description, which enables a client compiler to bind to the type description's members.
5 call_GetFuncDesc Retrieves the FUNCDESC structure that contains information about a specified function.
6 call_GetVarDesc Retrieves a VARDESC structure that describes the specified variable.
7 call_GetNames Retrieves the variable with the specified member ID (or the name of the property or method and its parameters) that correspond to the specified function ID.
8 call_GetRefTypeOfImplType If a type description describes a COM class, it retrieves the type description of the implemented interface types. For an interface, GetRefTypeOfImplType returns the type information for inherited interfaces, if any exist.
9 call_GetImplTypeFlags Retrieves the IMPLTYPEFLAGS enumeration for one implemented interface or base interface in a type description.
10 call_GetIDsOfNames Maps between member names and member IDs, and parameter names and parameter IDs.
11 call_Invoke Invokes a method, or accesses a property of an object, that implements the interface described by the type description.
12 call_GetDocumentation Retrieves the documentation string, the complete Help file name and path, and the context ID for the Help topic for a specified type description.
13 call_GetDllEntry Retrieves a description or specification of an entry point for a function in a DLL.
14 call_GetRefTypeInfo If a type description references other type descriptions, it retrieves the referenced type descriptions.
15 call_AddressOfMember Retrieves the addresses of static functions or variables, such as those defined in a DLL.
16 call_CreateInstance Creates a new instance of a type that describes a component object class (coclass).
17 call_GetMops Retrieves marshaling information.
18 call_GetContainingTypeLib Retrieves the containing type library and the index of the type description within that type library.
19 * call_ReleaseTypeAttr Releases a TYPEATTR previously returned by GetTypeAttr.
20 call_ReleaseFuncDesc Releases a FUNCDESC previously returned by GetFuncDesc.
21 call_ReleaseVarDesc Releases a VARDESC previously returned by GetVarDesc.
(only the * members are implemented)
Description
Retrieves a TYPEATTR structure that contains the attributes of the type description.
Usage
__WS_ITypeInfo_GetTypeAttr(pITypeInfo)
Parameters
Return Value
ErrorLevel
Remarks
TYPEATTR pointer should be freed via a call to __WS_ITypeInfo_ReleaseTypeAttr.
Used by __WS_GetIDispatch
Related
Description
Releases a TYPEATTR previously returned by __WS_ITypeInfo_GetTypeAttr.
Usage
__WS_ITypeInfo_ReleaseTypeAttr(pITypeInfo, pTypeAttr)
Parameters
Return Value
(Boolean) True on success, False on failure.
ErrorLevel
Remarks
Used by __WS_GetIDispatch
Related
VTable
0 call_QueryInterface Returns pointers to supported interfaces. 1 call_AddRef Increments reference count. 2 call_Release Decrements reference count. 3 * call_GetTypeInfoCount Retrieves the number of type information interfaces that an object provides (either 0 or 1). 4 * call_GetTypeInfo Gets the type information for an object. 5 call_GetIDsOfNames Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs. 6 call_Invoke Provides access to properties and methods exposed by an object. (only the * members are implemented)
Description
Retrieves the number of type information interfaces that an object provides (either 0 or 1).
Usage
__WS_IDispatch_GetTypeInfoCount(pIDispatch)
Parameters
Return Value
ErrorLevel
Remarks
Used by __WS_GetIDispatch
Related
Description
Gets the type information for an object.
Usage
__WS_IDispatch_GetTypeInfo(pIDispatch [, iLocaleID ] )
Parameters
Return Value
ErrorLevel
Remarks
Used by __WS_GetIDispatch
Related
VTable
0 * call_QueryInterface Returns pointers to supported interfaces. 1 * call_AddRef Increments reference count. 2 * call_Release Decrements reference count. (only the * members are implemented)
Description
Returns pointers to supported interfaces.
Usage
__WS_IUnknown_QueryInterface(pIUnknown, ?IId)
Parameters
Return Value
ErrorLevel
Remarks
Related
Description
Increments reference count.
Usage
__WS_IUnknown_AddRef(pIUnknown)
Parameters
Return Value
ErrorLevel
Remarks
Related
Description
Decrements reference count.
Usage
__WS_IUnknown_Release(pIUnknown)
Parameters
Return Value
ErrorLevel
Remarks
Related