home *** CD-ROM | disk | FTP | other *** search
- QuickVerse for Windows
- Dynamic Data Exchange Specification
- December, 1995
-
- *********************************************************************
- INTRODUCTION
- *********************************************************************
-
- This document specifies the Dynamic Data Exchange (DDE) support
- provided by QuickVerse for Windows (QV/Win). DDE is a method whereby
- two applications can communicate with one another using a standardized
- format. The two applications can share data as well as send and
- respond to commands that specific actions be performed.
-
- In every DDE conversation, one application is called the "client
- application" and the other is called the "server application." The
- client is the application that begins the conversation, requests data
- from the other application, and sends commands to the other
- application. The server application is the application that provides
- data to the client or that performs actions requested by the client.
- QuickVerse for Windows is capable of being both a DDE client and a DDE
- server. For example, when QuickVerse requests that PC Bible Atlas for
- Windows (PCBA/Win) show a map containing a city, then QuickVerse is
- acting as a DDE client. When another program requests that QuickVerse
- perform a Quick Paste operation, QuickVerse acts as a DDE server.
- This document provides specifications for both server and client DDE
- capability supported by QuickVerse.
-
- IMPORTANT NOTE: Due to substantial improvements in dynamic data
- exchange processing included with QuickVerse for Windows version 1.0i,
- we recommend that this version be the minimum program version used
- when using DDE with QuickVerse. You can determine your version of
- QuickVerse for Windows by referring to the "About Box" (select About
- QuickVerse from the Help menu).
-
- For specific information on using DDE with QuickVerse and another
- application, refer to this document and the other application's
- documentation. For specific information on how to write your own
- program that uses DDE, refer to chapter 15 of the Windows Software
- Developer Kit (SDK) volume 2 and chapter 17 of "Programming Windows
- 2nd edition" by Charles Petzold.
-
-
- *********************************************************************
- SERVER SPECIFICATION
- *********************************************************************
-
- GENERAL METHODOLOGY
- -------------------
-
- QuickVerse supports "cold" DDE links. Cold links allow information to
- be passed from one application to another without any additional
- updating being required or requested. Warm links and hot links are
- not required and are not supported.
-
- QuickVerse responds to the application name "QVWIN" and the topic name
- of "Verses." The primary DDE interface supported by QuickVerse is the
- WM_DDE_EXECUTE message. The QuickVerse server will respond to a
- variety of instructions (also called commands) passed with the
- WM_DDE_EXECUTE command. The QuickVerse server is also capable of
- responding to a WM_DDE_REQUEST message; however, the preferred
- interface is through the WM_DDE_EXECUTE message.
-
- QuickVerse responds to all WM_DDE_EXECUTE messages with a WM_DDE_ACK
- acknowledgement. A negative acknowledgement is sent if the command
- could not be completed; a positive acknowledgement indicates that the
- command was completed.
-
- SPECIFICATION FOR WM_DDE_EXECUTE
- --------------------------------
-
- The WM_DDE_EXECUTE message is used to pass commands to QV/Win. These
- commands can cause QV to perform a specific action (such as a search)
- or to provide information back to the caller (such as a version
- number). In all cases, the item string contains the command string.
- The command string is one or more execute commands and any of their
- associated parameters.
-
- The following execute commands are supported. The Syntax Version
- column specifies the syntax version of each command, and the Program
- Version column indicates which version of QuickVerse first supported
- the command. Detailed descriptions of these command are provided in a
- later section.
-
- Syntax Program
- Execute Command Version Version
- --------------------------------------------------------
- NULL 0 1.0c
- [QvPaste] 1 1.0f
- [GoTo("John 3:16")] 1 1.0f
- [Translation("KJV")] 1 1.0f
- [Minimize] 1 1.0f
- [Activate] 1 1.0f
- [QuickSearch("phrase")] 1 1.0g
- [RefSearch("ref")] 1 1.0i
- [LoadProgVersion(hmem)] 1 1.0i
- [LoadSyntaxVersion(hmem)] 1 1.0i
- [LoadCurrentTranslation(hmem)] 1 1.0i
- [LoadTranslations(hmem)] 1 1.0i
- [LoadVerseText(parameters)] 1 1.0i
-
- Beginning with version 1.0i of QuickVerse, QuickVerse can return the
- syntax level that it supports. A client application can determine
- which syntax level is supported to determine if QuickVerse will
- support a specific command. For instance, if a client application
- wants to send a "level 2 syntax" command to QuickVerse, it may first
- determine if QuickVerse supports that level of syntax. All levels are
- "backwards" compatible, so a program capable of support level 2 syntax
- also supports all level 0 and level 1 commands.
-
- Each command must be enclosed by brackets [ ] and each command may be
- separated by a space. Spaces within each command are not allowed,
- except in quoted strings. Parenthesis ( ) are used to begin and end
- the parameter list. All parameters are passed as strings and decoded
- depending upon the execute command. String parameters are expected to
- be enclosed by double-quotes, so the string parameter may not contain
- a double quote character. Parenthesis within quoted parameters are
- allowed.
-
- Multiple commands may be passed in one command string. For instance,
- to display John 3:16 in the King James Version, the following command
- string would be used.
-
- [Translation("KJV")][GoTo("John 3:16")]
-
- However, this is not recommended. By passing each command in a
- different WM_DDE_EXECUTE message, the return value may be examined to
- determine which command, if any, failed. The one exception to this
- recommendation is the [Activate] command, which is typically sent with
- some messages.
-
- If multiple commands are contained in one item, the commands will be
- processed from left to right. The process will abort and return a
- negative acknowledgement immediately upon encountering an error. That
- is, if the command string is
-
- [Translation("KJV")][GoTo("John 3:16")]
-
- and the KJV translation is unavailable, then the GoTo command will not
- be attempted.
-
- Additional details about each command are provided below.
-
- Application: QVWIN
- Topic: Verses
- Item: NULL
- Example: none
- Syntax Level: 0
-
- A null item causes QuickVerse to perform a QuickVerse paste.
- The preferred method of performing this is to use the
- [QvPaste] item (see below). Also note that all versions of
- QV/Win prior to version 1.0f will respond to _all_
- WM_DDE_EXECUTE messages by performing this action.
-
- Application: QVWIN
- Topic: Verses
- Item: [QvPaste]
- Example: [QvPaste]
- Syntax Level: 1
-
- This command is used to perform a QuickVerse Paste operation.
- It causes a dialog box to be displayed. The user can select a
- reference and a translation. The reference is copied to the
- clipboard from the specified translation using current
- clipboard setup settings.
-
- Application: QVWIN
- Topic: Verses
- Item: [GoTo("ref")]
- Example: [GoTo("John 3:16")]
- Syntax Level: 1
-
- This command causes QuickVerse to go to the specified
- reference in the currently active window. The reference is
- passed as a string, so it must be enclosed in double-quotes.
- The reference string must conform to standard QuickVerse
- references and is limited to 128 characters. An error occurs
- if there is not an active window. A multiple verse reference
- may be passed; in this case, the first verse in the reference
- string will be used.
-
- Application: QVWIN
- Topic: Verses
- Item: [Translation("abbr")]
- Example: [Translation("KJV")]
- Syntax Level: 1
-
- This command is used to activate the specified translation.
- Since some commands require a Bible window to be open, this
- command may be used to make sure that at least one Bible
- window is available before sending another command.
-
- The translation is passed as a string, so it must be enclosed
- in double-quotes. The translation is the standard
- abbreviation used by QuickVerse, and is limited to 4
- characters. (Use the LoadTranslations command to obtain a
- list of installed translations.) If the translation is
- already the active translation then nothing happens. If a
- window with the translation is open but not active, it is
- activated. If the translation is not open in any window, then
- a new window is opened to contain the translation. During the
- processing of this command, QV/Win may be temporarily
- activated. However, it returns activation to the previously
- active application when through.
-
- Application: QVWIN
- Topic: Verses
- Item: [Minimize]
- Example: [Minimize]
- Syntax Level: 1
-
- This command causes the whole QuickVerse application to be
- minimized (i.e. made into an icon), but does not activate it.
-
- Application: QVWIN
- Topic: Verses
- Item: [Activate]
- Example: [Activate]
- Syntax Level: 1
-
- This command causes QuickVerse to be activated. If it is
- minimized, it is also restored to normal size.
-
- Application: QVWIN
- Topic: Verses
- Item: [QuickSearch("phrase")]
- Example: [Activate][QuickSearch("Kingdom of God")]
- Syntax Level: 1
-
- This command is used to perform a QuickSearch on the given
- phrase. The phrase is passed as a string, so it must be
- enclosed by double-quotes. The phrase is limited to 128
- characters and 10 words. It may be any phrase supported by
- QuickVerse and may include Boolean operators and punctuation.
- QuickVerse may or may not be activated following this command;
- therefore, it is typical to use the activate command in
- conjunction with this command. An error occurs if there is
- not an active window.
-
- Application: QVWIN
- Topic: Verses
- Item: [RefSearch("ref")]
- Example: [RefSearch("John 3:16; Eph 2:8-9")]
- Syntax Level: 1
-
- This command instructs QuickVerse to perform a search for the
- specified references. The reference is passed as a string and
- therefore must be enclosed in double-quotes. The reference
- string may be up to 128 characters long and contain up to 10
- different references. QuickVerse may or may not be activated
- following this command; therefore, it is typical to use the
- activate command in conjunction with this command. An error
- occurs if there is not an active window.
-
- Application: QVWIN
- Topic: Verses
- Item: [LoadProgVersion(hmem)]
- Example: [LoadProgVersion(1234)]
- Syntax Level: 1
-
- This command causes QuickVerse to load the string identified
- by the memory handle "hmem" with the version of QuickVerse.
- hmem is converted from a string value into an unsigned integer
- (memory handle) with little error checking provided. An error
- occurs if hmem is not a valid memory handle, or if the memory
- it references is not large enough to contain the version
- string. The version string is something like "1.0i" where 1.0
- is the major version number and the last letter is the minor
- revision letter.
-
- Application: QVWIN
- Topic: Verses
- Item: [LoadSyntaxVersion(hmem)]
- Example: [LoadSyntaxVersion(1234)]
- Syntax Level: 1
-
- This command causes QuickVerse to load the syntax version that
- it supports into the memory identified by "hmem." hmem is
- converted from a string value into an unsigned integer (memory
- handle) with little error checking provided. An error occurs
- if hmem is not a valid memory handle. The memory identified
- is loaded with an integer value (i.e. not a string
- representation of an integer) such as 1, 2, etc.
-
- It is recommended that client applications use this command to
- determine if QuickVerse supports the commands that the client
- supports. Versions of QuickVerse prior to version 1.0i,
- however, do not support this command.
-
- Application: QVWIN
- Topic: Verses
- Item: [LoadCurrentTranslation(hmem)]
- Example: [LoadTranslations(1234)]
- Syntax Level: 1
-
- This command causes QuickVerse to load the string identified
- by the memory handle hmem with the abbreviation of the
- translation being used by the active window. hmem is
- converted from a string value into an unsigned integer
- (memory handle) with little error checking provided. An
- error occurs if hmem is not a valid memory handle, or if
- the memory it references is not large enough to contain
- the translation abbreviation.
-
- The string contains only the abbreviation of the current
- translation. For example, if the King James Version is
- active, the string would contain "KJV".
-
- Application: QVWIN
- Topic: Verses
- Item: [LoadTranslations(hmem)]
- Example: [LoadTranslations(1234)]
- Syntax Level: 1
-
- This command causes QuickVerse to load a string containing a
- list of the installed translations into the memory identified
- by the memory handle hmem. hmem is converted from a string
- value into an unsigned integer (memory handle) with little
- error checking provided. An error occurs if hmem is not a
- valid memory handle, or if the memory it references is not
- large enough to contain the string of translations. The
- loaded string contains the abbreviations of the translations
- that are installed, with a space separating each entry.
- "KJV NIV RSV" is an example returned string.
-
- Application: QVWIN
- Topic: Verses
- Item: [LoadVerseText(hmem, flags, "ref")]
- Example: [LoadVerseText(1234,0,"John 3:16-18")]
- Syntax Level: 1
-
- This command is used to request that QuickVerse load the
- specified memory handle (hmem) with verse text from the
- active translation. An error occurs if there is not an
- active window. Also note that there may not be any spaces
- included in the list of parameters (the example above is
- correct).
-
- The "flags" parameter is a 2-byte bit field. The individual
- bits in this flag can be used to specify the format of the
- text that is loaded. You may specify a flag value of 0 to
- use default settings. In the following table, the bit
- position is from least significant to most significant (that
- is, Bit 0 is the least significant (right-most) bit).
-
- Bit(s) Value Definition
- -----------------------------------------------------------
- 0 0 use plain text format
- 1 use rich text format (rtf)
- 1 0 don't use a cancel dialog box
- 1 use a cancel dialog box
- 2 0 when using rtf, don't use bold codes
- 1 when using rtf, use bold codes
- 3 0 when using rtf, don't use italics codes
- 1 when using rtf, use italics codes
- 4 0 when using rtf, don't use red codes
- 1 when using rtf, use red codes
- 5 0 don't includes quotes around verses
- 1 include quotes around verses
- 6 0 use full book names
- 1 use abbreviated book names
- 7 0 don't include verse and word notes
- 1 include verse and word notes
- 8 0 don't include book notes
- 1 include book notes
- 9 0 don't include chapter notes
- 1 include chapter notes
- 10 0 don't include translation with reference
- 1 include translation with reference
- 11-13 0 reference followed by verse format
- 1 verse followed by reference format
- 2 verse only format (no reference)
- 3 reference above verse format
- 4 reference only format (no verse)
- 5 paragraph format
- 14-15 0 use Strong's numbers only
- 1 use transliterated HG word only
- 2 use both word and Strong's number
-
- Bits 14 and 15 are valid only when the Hebrew and Greek
- Transliterated Bible is being exported.
-
- As previously noted, QuickVerse will respond to the WM_DDE_EXECUTE
- messages with a WM_DDE_ACK message. A positive acknowledgement is
- sent when the command was successful; a negative acknowledgement is
- sent otherwise. Information about the WM_DDE_ACK message and error
- handling is provided in a following section.
-
- Additional commands may be added in later editions of QuickVerse. If
- so, these commands will be identified with a new syntax version. This
- allows a client application to determine which commands are available
- before trying to use one.
-
- SPECIFICATION FOR WM_DDE_REQUEST
- --------------------------------
-
- The WM_DDE_REQUEST message is used to request QV/Win to place the text
- for a specified passage in DDE shared memory that can then be used by
- the client application. The preferred method of performing this
- activity is with the LoadVerseText execute command discussed above.
-
- The DDE conversation must be initiated with an application name of
- "QVWIN" and a topics name of "Verses." wParam of the WM_DDE_REQUEST
- message is the handle to the DDE client window. The low word of
- lParam is the requested clipboard format. CF_TEXT and rich text
- format are supported. To obtain the rich text format specifier, use
- the RegisterClipboardFormat("Rich Text Format") API. The high word of
- lParam is an atom containing the requested verse reference or
- references.
-
- In response to this message, QuickVerse will allocate DDE shared
- memory and transfer the text into this memory. QuickVerse will then
- post a WM_DDE_DATA message. The low word of lParam contains the
- handle to the DDEDATA memory block. The values stored in this memory
- block are shown below.
-
- Field Value Explanation
- -------------------------------------------------------------
- fResponse TRUE The client application is expected to
- free the memory object.
- fRelease TRUE This data is offered in response to a
- WM_DDE_REQUEST message.
- reserved FALSE Reserved by Windows.
- fAckReq TRUE The client application is expected to
- send a WM_DDE_ACK message after the
- WM_DDE_DATA message has been
- processed.
- cfFormat CF_TEXT Format of the data in the value
- field.
- Value hMem Handle to the memory block
- containing the verse text.
-
- The client window is expected to send a WM_DDE_ACK message to
- QuickVerse after the WM_DDE_DATA message has been processed. If the
- client window does not respond within a specified time period,
- QuickVerse will free the memory blocks it allocated for the
- WM_DDE_DATA message.
-
- If the requested data can not be provided, QuickVerse will respond by
- sending a WM_DDE_ACK message with a negative acknowledgement) instead
- of the WM_DDE_DATA message. See the following section on error
- handling for more details.
-
- ERROR HANDLING
- --------------
-
- The client application can generally rely upon QuickVerse to display
- an error message that describes the error condition.
-
- In addition, QuickVerse responds to all WM_DDE_EXECUTE messages and
- failure conditions for WM_DDE_REQUEST with a WM_DDE_ACK message. A
- DDEACK structure accompanies the acknowledge message. This structure
- contains 3 fields of interest: fAck, fBusy, and bAppReturnCode. The
- fAck flag contains the acknowledgement. A positive acknowledgement is
- sent if the command string was completely executed; otherwise a
- negative acknowledgement is sent. The remaining two fields contain
- information about the failure, since there may be many reasons that
- the commands were not completed.
-
- The client application should not assume that the command was
- unrecognized if a negative acknowledgement was received. If a
- negative acknowledgement is received, the client application should
- first examine the fBusy flag. If this flag is set, then QuickVerse
- did not execute the commands because it was busy. Additionally, the
- bAppReturnCode field may contain additional information about why a
- negative acknowledgement was received. Since QuickVerse will
- generally display a message to the user when a bona-fide error occurs,
- the client application does not need to examine the application error
- code. However, it is provided for convenience.
-
- The following application return codes are provided.
-
- bAppReturnCode Description
- ----------------------------------------------------------------
- 0 Additional information about the error source
- is not provided.
-
- 1 Busy. QuickVerse did not respond because it
- was busy. QuickVerse is "busy" when a modal
- dialog box is displayed, or when an error message
- is displayed, or when QuickVerse is still
- processing a previous DDE message.
- Note that the client application should not rely
- on this value, but should instead check the fBusy
- field to determine if the command failed because
- QuickVerse was busy.
-
- 2 The DDE message is not supported by QuickVerse.
- The WM_DDE_ADVISE is an example of this.
-
- 3 An unrecognized execute command was received.
-
- 4 The command contained a syntax error or an invalid
- parameter. This code is also returned when the
- command does not provide a valid memory handle.
-
- 5 The operation failed. This can occur when an
- active window is required, but not available, or
- when memory was not available.
-
- 6 A system error occurred. These are rather severe
- and occur only when a system level activity (such
- as atom string retrieval or posting a message)
- fail.
-
-
- *********************************************************************
- CLIENT SPECIFICATION
- *********************************************************************
-
- GENERAL METHODOLOGY
- -------------------
-
- QuickVerse can serve as a DDE client application and pass instructions
- to other applications with the WM_DDE_EXECUTE command.
-
- NOTES FOR ALL SERVER APPLICATIONS
- ---------------------------------
-
- One important note is that QuickVerse expects a WM_DDE_ACK message to
- be received within a specified period after sending the execute
- command. If the message is not received, QuickVerse will prompt the
- user about whether or not to continue waiting. The server program
- should, therefore, send an acknowledge message promptly.
-
- QuickVerse checks the returned acknowledgement for a positive or
- negative acknowledgement, as well as the busy flag as appropriate. It
- does not check the bAppReturnCode flag.
-
- SPECIFICATION FOR THE INTERFACE TO A BIBLE ATLAS
- ------------------------------------------------
-
- A QuickVerse user can choose the Bible Atlas program that QuickVerse
- interacts with. While QuickVerse is designed to be used with PC Bible
- Atlas for Windows, any Bible Atlas program that supports the
- following WM_DDE_EXECUTE commands may be used.
-
- Application: User defined
- Topic name: Commands
-
- Syntax Program Version
- Item Level Used In
- ------------------------------------------------------------
- [Show("item")] 1 1.0i
- [Activate] 1 1.0i
- [LoadSyntaxVersion(hmem)] 1 1.0i
-
- Refer to the DDE Specification for PC Bible Atlas for Windows for more
- detail regarding these specific commands.
-
- SPECIFICATION FOR THE INTERFACE TO A BIBLE DICTIONARY
- -----------------------------------------------------
-
- A QuickVerse user can choose the dictionary program that QuickVerse
- interacts with. While QuickVerse is designed to be used with the
- Holman Bible Dictionary, and dictionary that supports the following
- WM_DDE_EXECUTE commands may be used.
-
- Application: User defined
- Topic name: Commands
-
- Syntax Program Version
- Item Level Used In
- ------------------------------------------------------------
- [Show("item")] 1 1.0j
- [ShowVerseRefs("ref")] 1 1.0j
- [Activate] 1 1.0j
- [LoadSyntaxVersion(hmem)] 1 1.0j
-
- Refer to the DDE Specification for the Holman Bible Dictionary
- for more detail regarding these specific commands.
-
- SPECIFICATION FOR THE INTERFACE TO BIBLE ILLUSTRATOR
- ----------------------------------------------------
-
- QuickVerse is designed to be used with Bible Illustrator for
- Windows, but may be used with any illustration program that
- supports the correct syntax. The following WM_DDE_EXECUTE
- commands may be used.
-
- Application: User defined
- Topic name: Commands
-
- Syntax Program Version
- Item Level Used In
- ------------------------------------------------------------
- [Show("item")] 1 3.0c
- [ShowVerseRefs("ref")] 1 3.0c
- [Activate] 1 3.0c
- [LoadSyntaxVersion(hmem)] 1 3.0c
-
- Refer to the DDE Specification for Bible Illustrator for more
- detail regarding these specific commands.
-
- SPECIFICATION FOR THE INTERFACE TO THE QUICKVERSE LIBRARY
- ---------------------------------------------------------
-
- QuickVerse is designed to be used with the QuickVerse Library,
- but it can be used with any reference library that supports
- the following commands.
-
- Application: User defined
- Topic name: Commands
-
- Syntax Program Version
- Item Level Used In
- ------------------------------------------------------------
- [Activate] 1 3.0j
- [Minimize] 1 3.0j
- [Synchronize(#,#,#)] 1 3.0j
- [WordSearch("word","language")] 1 3.0j
- [WordSync("word")] 1 3.0j
- [VerseSearch("ref")] 1 3.0j
- [VerseSync("ref")] 1 3.0j
-
- Refer to the DDE Specification for the QuickVerse Library
- for more detail regarding these specific commands.
-
-
-