Difference between revisions of "ISXDK"

From Lavish Software Wiki
Jump to navigation Jump to search
 
(9 intermediate revisions by 3 users not shown)
Line 6: Line 6:
  
 
== Getting Started with ISXDK ==
 
== Getting Started with ISXDK ==
 +
 +
The latest version of ISXDK can be downloaded from the [http://www.lavishsoft.com/downloads.php Lavish Software downloads page].
 +
 +
 
The following ISXDK documentation will assume, in most cases, that you are a proficient C++ developer.  This is not a C/C++ tutorial -- if you need one, please start by finding one.  You should at least be familiar with calling conventions and function prototypes before attempting to create an extension (specifically, you need to know why your functions need to look exactly like the examples).  You should also be aware of what a struct is, and understand that a LavishScript data type does not replace a struct -- it is a window into a data structure for scripts.
 
The following ISXDK documentation will assume, in most cases, that you are a proficient C++ developer.  This is not a C/C++ tutorial -- if you need one, please start by finding one.  You should at least be familiar with calling conventions and function prototypes before attempting to create an extension (specifically, you need to know why your functions need to look exactly like the examples).  You should also be aware of what a struct is, and understand that a LavishScript data type does not replace a struct -- it is a window into a data structure for scripts.
  
Line 17: Line 21:
  
 
Your command functions need to return a value.  Returning a negative number indicates a fatal error that should immediately end the script, if any.  If you need to indicate such an error, you should return -1, in case other values are used for different purposes in the future.  Returning a number greater than or equal to 0 indicates success.  0 should always indicate a plain old "success".  You may choose to return different positive values to indicate different success conditions for future use.  At present, the return value is not used other than to check for an error that should end the script, but it will be accessible to scripts in a future release.  No positive return values will be reserved for future use by LavishScript.
 
Your command functions need to return a value.  Returning a negative number indicates a fatal error that should immediately end the script, if any.  If you need to indicate such an error, you should return -1, in case other values are used for different purposes in the future.  Returning a number greater than or equal to 0 indicates success.  0 should always indicate a plain old "success".  You may choose to return different positive values to indicate different success conditions for future use.  At present, the return value is not used other than to check for an error that should end the script, but it will be accessible to scripts in a future release.  No positive return values will be reserved for future use by LavishScript.
 +
 +
See [[ISXDK:Commands|Commands]] for complete information.
  
 
==== Data Types ====
 
==== Data Types ====
Datatypes are the "class" or "struct" of LavishScript.  A LavishScript datatype is defined by creating an LSType-derived class, and calling the function designed to add the type definition to the engine.  Datatypes generally encompass any operation that would be performed on or with a C++ class or C struct or datatype.  Datatypes are usually created for each class or structure that needs to be used, with exception when it would be simpler in a script to access deeper information as a direct member or method of a parent object (e.g. data in a child structure that is only used in a certain class or struct does not necessitate another LavishScript datatype).  LavishScript datatypes are just a way of accessing things of a given C/C++ type from a script!
+
Data types are the "class" or "struct" of LavishScript.  A LavishScript datatype is defined by creating an LSType-derived class, and calling the function designed to add the type definition to the engine.  Datatypes generally encompass any operation that would be performed on or with a C++ class or C struct or datatype.  Datatypes are usually created for each class or structure that needs to be used, with exception when it would be simpler in a script to access deeper information as a direct member or method of a parent object (e.g. data in a child structure that is only used in a certain class or struct does not necessitate another LavishScript datatype).  LavishScript datatypes are just a way of accessing things of a given C/C++ type from a script!
 +
 
 +
See [[ISXDK:Data Types|Data Types]] for complete information.
  
 
==== Services ====
 
==== Services ====
 
Services provide an alternate method of two-way communications between Inner Space and an extension, or even between extensions.  Services do not require changes to the interfaces, and each service is completely independent of the ISXDK.  The ISXDK provides helper functions and structures for the built-in services, including the HTTP service, Pulse service, Console service, and so on.  Services work by sending broadcast or targeted messages, usually along with a pointer to data.  The service host and clients need to know what messages are available, and what data is associated with the messages they need to send or receive.
 
Services provide an alternate method of two-way communications between Inner Space and an extension, or even between extensions.  Services do not require changes to the interfaces, and each service is completely independent of the ISXDK.  The ISXDK provides helper functions and structures for the built-in services, including the HTTP service, Pulse service, Console service, and so on.  Services work by sending broadcast or targeted messages, usually along with a pointer to data.  The service host and clients need to know what messages are available, and what data is associated with the messages they need to send or receive.
 +
 +
See [[ISXDK:Services|Services]] for complete information.
  
 
==== Top-Level Objects ====
 
==== Top-Level Objects ====
Top-Level Objects are like smart global variables, and variables ''are'' actually Top-Level Objects (variables are objects, too, and Top-Level simply means it's a starting point).  The difference is that a Top-Level Object is able to process information given to it, such as search parameters, with the ability to return any object of any given datatype, whereas a variable is simply limited by its datatype.  In fact, a Top-Level Object can be seen as accessing a member of a universal, unnamed object, and is coded exactly in that way. A Top-Level Object function definition is the same as a datatype "GetMember" function, but without the parent class and without the current object or member name parameters.
+
Top-Level Objects are like smart global variables, and variables ''are'' actually Top-Level Objects (variables are objects, too, and Top-Level simply means it's a starting point).  The difference is that a Top-Level Object is able to process information given to it, such as search parameters, with the ability to return any object of any given datatype, whereas a variable is simply limited by its datatype.  In fact, a Top-Level Object can be seen as accessing a member of a universal, unnamed object, and is coded exactly in that way: A Top-Level Object function definition is the same as a datatype "GetMember" function, but without the parent class and without the current object or member name parameters.
  
 
Top-Level Objects are defined much like commands, but slightly different.  The standard argc and argv parameters are used, but the name of the Top-Level Object is *not* given as the first argument (this is also the case for datatype members).
 
Top-Level Objects are defined much like commands, but slightly different.  The standard argc and argv parameters are used, but the name of the Top-Level Object is *not* given as the first argument (this is also the case for datatype members).
 +
 +
See [[ISXDK:Top-Level Objects|Top-Level Objects]] for complete information.
  
 
=== Utilities ===
 
=== Utilities ===
 
==== mkisx ====
 
==== mkisx ====
The mkisx utility generates an ISX (Inner Space Extension) project with everything necessary to get started creating your extension.  Whether you are new to C++, new to ISXDK, or a seasoned veteran of both, this utility should serve as your starting point for all of your IS extensions.  This utility is a command-line utility, though a GUI will be added later.  To use it, put the name of your new project as a parameter.  The project will be created, prepended with ISX, in its own subdirectory from the current location.  The .vcproj file can then be loaded by any version of MS Visual Studio .Net, or the .dsp file can be loaded for Visual Studio 6.  We do not officially support Visual Studio 6, as it is out of the Microsoft support cycle and no longer receives updates.
+
The mkisx utility generates an ISX (Inner Space Extension) project with everything necessary to get started creating your extension.  Whether you are new to C++, new to ISXDK, or a seasoned veteran of both, this utility should serve as your starting point for all of your IS extensions.  This utility is a command-line utility, though a GUI will be added later.  To use it, put the name of your new project as a parameter.  The project will be created, prepended with ISX, in its own subdirectory from the current location.  The .vcproj file can then be loaded by any version of MS Visual Studio .Net, or Visual Studio 2005.
  
 
==== Struct2LSType ====
 
==== Struct2LSType ====
Line 50: Line 62:
 
# [[ISXDK:Running a Script or Command File|Running a Script or Command File]]
 
# [[ISXDK:Running a Script or Command File|Running a Script or Command File]]
 
# [[ISXDK:Parsing Data Sequences|Parsing Data Sequences]]
 
# [[ISXDK:Parsing Data Sequences|Parsing Data Sequences]]
 +
# [[ISXDK:Exposing API to .NET 2.0 Assemblies|Exposing API to .NET 2.0 Assemblies]]
  
 
== Samples ==
 
== Samples ==
Line 74: Line 87:
 
*[[ISXDK:ISInterface|ISInterface]]
 
*[[ISXDK:ISInterface|ISInterface]]
 
*[[ISXDK:ISXInterface|ISXInterface]]
 
*[[ISXDK:ISXInterface|ISXInterface]]
*[[ISXDK:LSType|LSType]]
+
*[[ISXDK:LSTypeDefinition|LSTypeDefinition]]
  
 
===Functions===
 
===Functions===

Latest revision as of 01:18, 1 December 2006

Introduction

ISXDK, short for Inner Space Extension Development Kit, is used for developing extensions for Inner Space sessions.

Installation

Installation of ISXDK is very simple. Download and run the installer, and have it install to anywhere you want -- it doesn't matter where it is in relation to your source code, so long as you remember where it is. After installation, you need to add the include and library paths to Visual Studio so they will be used automatically when you #include <isxdk.h> from your code and link to isxdk.lib.

Getting Started with ISXDK

The latest version of ISXDK can be downloaded from the Lavish Software downloads page.


The following ISXDK documentation will assume, in most cases, that you are a proficient C++ developer. This is not a C/C++ tutorial -- if you need one, please start by finding one. You should at least be familiar with calling conventions and function prototypes before attempting to create an extension (specifically, you need to know why your functions need to look exactly like the examples). You should also be aware of what a struct is, and understand that a LavishScript data type does not replace a struct -- it is a window into a data structure for scripts.

This section of the documentation explains the basics of the ISXDK, and each of the main things that you may be developing in an Inner Space extension.

Concepts

Inner Space extensions, on the most basic level, simply deal with an extension interface (ISXInterface) and the Inner Space interface (ISInterface). These interfaces provide a method of two-way communication between your extension and Inner Space. Inner Space generally does not need anything from your extension -- just initialization, shutdown, and version. These are the three functions your extension will provide that are accessible to Inner Space (though the version function is hidden to you). Your extension, however, needs many functions from Inner Space. (ISInterface) provides many fuctions to allow your extension to do everything you want it to do. If anything is missing that you feel you need access to, make sure to ask and it may be provided in a new ISXDK version.

Commands

Commands provide an interface for the end user to control your functionality. Commands are actually extensions to LavishScript rather than Inner Space, though you pass your command definitions to LavishScript through the Inner Space interface. LavishScript command functions follow the standard prototype for a console program -- int __cdecl main(int argc, char *argv[]). As with console programs, argv[0] is the name of the command and is included in argc. The actual arguments start with argv[1].

Your command functions need to return a value. Returning a negative number indicates a fatal error that should immediately end the script, if any. If you need to indicate such an error, you should return -1, in case other values are used for different purposes in the future. Returning a number greater than or equal to 0 indicates success. 0 should always indicate a plain old "success". You may choose to return different positive values to indicate different success conditions for future use. At present, the return value is not used other than to check for an error that should end the script, but it will be accessible to scripts in a future release. No positive return values will be reserved for future use by LavishScript.

See Commands for complete information.

Data Types

Data types are the "class" or "struct" of LavishScript. A LavishScript datatype is defined by creating an LSType-derived class, and calling the function designed to add the type definition to the engine. Datatypes generally encompass any operation that would be performed on or with a C++ class or C struct or datatype. Datatypes are usually created for each class or structure that needs to be used, with exception when it would be simpler in a script to access deeper information as a direct member or method of a parent object (e.g. data in a child structure that is only used in a certain class or struct does not necessitate another LavishScript datatype). LavishScript datatypes are just a way of accessing things of a given C/C++ type from a script!

See Data Types for complete information.

Services

Services provide an alternate method of two-way communications between Inner Space and an extension, or even between extensions. Services do not require changes to the interfaces, and each service is completely independent of the ISXDK. The ISXDK provides helper functions and structures for the built-in services, including the HTTP service, Pulse service, Console service, and so on. Services work by sending broadcast or targeted messages, usually along with a pointer to data. The service host and clients need to know what messages are available, and what data is associated with the messages they need to send or receive.

See Services for complete information.

Top-Level Objects

Top-Level Objects are like smart global variables, and variables are actually Top-Level Objects (variables are objects, too, and Top-Level simply means it's a starting point). The difference is that a Top-Level Object is able to process information given to it, such as search parameters, with the ability to return any object of any given datatype, whereas a variable is simply limited by its datatype. In fact, a Top-Level Object can be seen as accessing a member of a universal, unnamed object, and is coded exactly in that way: A Top-Level Object function definition is the same as a datatype "GetMember" function, but without the parent class and without the current object or member name parameters.

Top-Level Objects are defined much like commands, but slightly different. The standard argc and argv parameters are used, but the name of the Top-Level Object is *not* given as the first argument (this is also the case for datatype members).

See Top-Level Objects for complete information.

Utilities

mkisx

The mkisx utility generates an ISX (Inner Space Extension) project with everything necessary to get started creating your extension. Whether you are new to C++, new to ISXDK, or a seasoned veteran of both, this utility should serve as your starting point for all of your IS extensions. This utility is a command-line utility, though a GUI will be added later. To use it, put the name of your new project as a parameter. The project will be created, prepended with ISX, in its own subdirectory from the current location. The .vcproj file can then be loaded by any version of MS Visual Studio .Net, or Visual Studio 2005.

Struct2LSType

Struct2LSType reads in C headers, and outputs text to be copied and pasted into your extension to form LavishScript data types that directly access structures.

Tutorials

  1. Creating a Basic Extension
  2. Printing Text to the Console
  3. Adding a Command
  4. Adding a Top-Level Object
  5. Adding a Data Type
  6. Adding a Service
  7. Connecting to an Existing Service
  8. Adding a Trigger
  9. Retrieving a Web Page
  10. Using the Pulse Service for Constant Processing
  11. Using XML Setting Files
  12. Running a Script or Command File
  13. Parsing Data Sequences
  14. Exposing API to .NET 2.0 Assemblies

Samples

Reference

Callback Functions

Classes

Functions

Macros

Structures

See Also