Adds a code scriptlet to the script. This method is used in environments where the persistent state of the script is intertwined with the host document and the host is responsible for restoring the script, rather than through an IPersist* interface. The primary examples are HTML scripting languages that allow scriptlets of code embedded in the HTML document to be attached to intrinsic events (for instance, ONCLICK="button1.text='Exit'").
HRESULT AddScriptlet(
LPCOLESTR pstrDefaultName, // address of default name of scriptlet
LPCOLESTR pstrCode, // address of scriptlet text
LPCOLESTR pstrItemName, // address of item name
LPCOLESTR pstrSubItemName, // address of subitem name
LPCOLESTR pstrEventName, // address of event name
LPCOLESTR pstrDelimiter, // address of end-of-scriptlet delimiter
DWORD_PTR dwSourceContextCookie, // application-defined value for debugging
ULONG ulStartingLineNumber, // starting line of the script
DWORD dwFlags, // scriptlet flags
BSTR *pbstrName, // address of actual name of scriptlet
EXCEPINFO *pexcepinfo // address of exception information
);
- pstrDefaultName
[in] Address of a default name to associate with the scriptlet. If the scriptlet does not contain naming information (as in the ONCLICK example above), this name will be used to identify the scriptlet. If this parameter is NULL, the scripting engine manufactures a unique name, if necessary.
- pstrCode
[in] Address of the scriptlet text to add. The interpretation of this string depends on the scripting language.
- pstrItemName
[in] Address of a buffer that contains the item name associated with this scriptlet. This parameter, in addition to pstrSubItemName, identifies the object for which the scriptlet is an event handler.
- pstrSubItemName
[in] Address of a buffer that contains the name of a subobject of the named item with which this scriptlet is associated; this name must be found in the named item's type information. This parameter is NULL if the scriptlet is to be associated with the named item instead of a subitem. This parameter, in addition to pstrItemName, identifies the specific object for which the scriptlet is an event handler.
- pstrEventName
[in] Address of a buffer that contains the name of the event for which the scriptlet is an event handler.
- pstrDelimiter
[in] Address of the end-of-scriptlet delimiter. When the pstrCode parameter is parsed from a stream of text, the host typically uses a delimiter, such as two single quotation marks (''), to detect the end of the scriptlet. This parameter specifies the delimiter that the host used, allowing the scripting engine to provide some conditional primitive preprocessing (for example, replacing a single quotation mark ['] with two single quotation marks for use as a delimiter). Exactly how (and if) the scripting engine makes use of this information depends on the scripting engine. Set this parameter to NULL if the host did not use a delimiter to mark the end of the scriptlet.
- dwSourceContextCookie
[in] Application-defined value that is used for debugging purposes.
- ulStartingLineNumber
[in] Zero-based value that specifies which line the parsing will begin at.
- dwFlags
[in] Flags associated with the scriptlet. Can be a combination of the following values:
Return Value | Meaning |
|---|---|
SCRIPTTEXT_ISVISIBLE | Indicates that the script text should be visible (and, therefore, callable by name) as a global method in the name space of the script. |
SCRIPTTEXT_ISPERSISTENT | Indicates that the code added during this call should be saved if the scripting engine is saved (for example, through a call to IPersist*::Save), or if the scripting engine is reset by way of a transition back to the initialized state. For more information about this state, see Script Engine States. |
- pbstrName ,
[out] Actual name used to identify the scriptlet. This is to be in order of preference: a name explicitly specified in the scriptlet text, the default name provided in pstrDefaultName, or a unique name synthesized by the scripting engine.
- pexcepinfo ,
[out] Address of a structure containing exception information. This structure should be filled in if DISP_E_EXCEPTION is returned.
Returns one of the following values:
Return Value | Meaning |
|---|---|
S_OK | Success. |
DISP_E_EXCEPTION | An exception occurred in the parsing of the scriptlet. The pexcepinfo parameter contains information about the exception. |
E_INVALIDARG | An argument was invalid. |
E_NOTIMPL | This method is not supported; the scripting engine does not support adding event-sinking scriptlets. |
E_POINTER | An invalid pointer was specified. |
E_UNEXPECTED | The call was not expected (for example, the scripting engine has not yet been loaded or initialized) and therefore failed. |
OLESCRIPT_E_INVALIDNAME | The default name supplied is invalid in this scripting language. |
OLESCRIPT_E_SYNTAX | An unspecified syntax error occurred in the scriptlet. |