Inter-Application Message Pipe Functions supported by Turbo ST -------------------------------------------------------------- The following is a list of functions supported by Turbo ST as of version 1.8 allowing applications or desk accessories to communicate with and/or control THE DESK ACCESSORY VERSION of Turbo ST. References to "the application" in the following documentation refer to either a desk accessory or GEM application. The auto folder versions of Turbo ST do not support the GEM message pipelines because they serve as "true" TSR's, and do not wait for an event from the GEM Desktop. (1) Request to determine if Turbo ST is active. The application sends a message of the following format to Turbo ST: message[0] = $1000 message[1] = application's id message[2] = 0 message[3] = -1 message[4] = unused message[5] = unused message[6] = unused message[7] = unused Turbo ST then sends a message of the following format back to the application: message[0] = $1001 message[1] = Turbo ST's application id message[2] = 0 message[3] = Turbo ST active flag message[4] = unused message[5] = unused message[6] = unused message[7] = unused A "0" is returned in message[3] if Turbo ST is inactive. A "1" is returned in message[3] if Turbo ST is active. (2) Request by the application to turn Turbo ST on or off. The application sends a message of the following format to Turbo ST: message[0] = $1000 message[1] = application's id message[2] = 0 message[3] = Turn Turbo ST off/on flag message[4] = unused message[5] = unused message[6] = unused message[7] = unused To turn Turbo ST off place a "0" in message[3]. To turn Turbo ST on place a "1" in message[3]. Turbo ST then sends a message of the following format back to the application: message[0] = $1001 message[1] = Turbo ST's application id message[2] = 0 message[3] = previous state of Turbo ST message[4] = unused message[5] = unused message[6] = unused message[7] = unused If Turbo ST was previously inactive a "0" is returned in message[3]. A "1" returned in message[3] signifies that Turbo ST was previously active. A Little Note of Caution ------------------------ MAKE SURE THAT YOU CHECK FOR THE EXISTENCE OF TURBO ST IN THE SYSTEM VIA APPL_FIND() BEFORE USING APPL_WRITE() TO SEND MESSAGES TO TURBO ST ! IF YOU DO NOT FOLLOW SUCH A PRACTICE YOUR APPLICATION WILL "HANG" FOLLOWING THE CALL TO APPL_WRITE, SINCE TURBO ST WILL NOT BE THERE TO RESPOND. An Example of Interacting with Turbo ST 1.8+ -------------------------------------------- The following is a small code segment that will illustrate how to perform the following functions: (1) Determine whether or not the COLOR version of the Turbo ST Desk Accessory is present in the system. (2) Inquire about Turbo ST's present installation state (whether Turbo ST is on or off). (3) Turn Turbo ST OFF. (4) Turn Turbo ST ON. The example is written in the excellent HiSoft assembly language development system, DevPac ST. If you feel that 68000 assembly code is the greatest thing since the novels of Emile Zola (like us), then run to your nearest dealer and buy it immediately ! ***************************************************************** * EXAMPLE INTERACTIONS WITH TURBO ST * ***************************************************************** * register equates AESID equr D5 * AES id code VDIID equr D6 * VDI id code CONTROL equr A1 * pointer to the Control array AESPRM equr A3 * pointer to the AES parameter block : : etc : : ***************************************************************** * DETERMINE WHETHER TURBO ST IS PRESENT IN THE SYSTEM * ***************************************************************** * get the application id of the Turbo ST desk accessory, so as to communicate move.l CONTROL,A0 * get a pointer to the Contrl array move.w #13,(A0)+ * determine the application's id, appl_find() clr.w (A0)+ * size of the IntIn array move.w #1,(A0)+ * size of the IntOut array move.w #1,(A0)+ * size of the AddrIn array clr.w (A0) * size of the AddrOut array move.l #DeskName,AddrIn * get a pointer to the name of the Turbo ST desk accessory move.w AESID,D0 * get the AES identification code move.l AESPRM,D1 * get a pointer to the AES parameter block trap #2 * call GEM move.w IntOut(PC),TurboId * save the Turbo ST desk accessory id cmp.w #-1,TurboId * Turbo ST not present ? beq Abort * yes, abort the example ************************************************************ * DETERMINE THE CURRENT STATUS OF TURBO ST * ************************************************************ * determine the current status of Turbo ST lea MsgBuff(PC),A0 * get a pointer to the message buffer move.w #$1000,(A0)+ * "determine the status of Turbo ST" move.w AppId(PC),(A0)+ * application id of RndRect() clr.w (A0)+ * message is standard 8 word size move.w #-1,(A0)+ * "get the current state of Turbo ST" move.l CONTRL,A0 * get a pointer to the Contrl array move.w #12,(A0)+ * write message through pipe, appl_write() move.w #2,(A0)+ * size of the integer input array clr.w (A0)+ * size of the integer output array move.w #1,(A0)+ * size of the address input array clr.w (A0)+ * size of the address output array move.w TurboId(PC),IntIn * application id of Turbo ST move.w #16,IntIn+2 * size of the message (bytes) move.l #MsgBuff,AddrIn * address of the message buffer move.w AESID,D0 * get the AES indentification code move.l AESPRM,D1 * get a pointer to the AES parameter block trap #2 * call GEM * wait for Turbo ST to return information about its current status waitStat move.l CONTROL,A0 * get a pointer to the Contrl array move.w #23,(A0)+ * wait for a message, evnt_mesag() clr.l (A0)+ * size of the IntIn and IntOut arrays move.w #1,(A0)+ * size of the address input array clr.w (A0)+ * size of the address output array move.l #MsgBuff,AddrIn * get a pointer to the message event buffer move.w AESID,D0 * get the AES indentification code move.l AESPRM,D1 * get a pointer to the AES parameter block trap #2 * call GEM cmp.w #$1001,MsgBuff * has Turbo ST responded ? bne.s waitStat * no, wait for the message event again move. MsgBuff+6(PC),D0 * get the current installation status move.w D0,CurrSt * save the current installation state of Turbo ST move.w D0,OrigSt * save as the original installation status of Turbo ST ***************************************************** * TELL TURBO ST TO TURN ITSELF OFF * ***************************************************** * request that Turbo ST turn itself OFF lea MsgBuff(PC),A0 * get a pointer to the message buffer move.w #$1000,(A0)+ * turn Turbo ST on or off move.w AppId(PC),(A0)+ * application id of test program clr.w (A0)+ * message is standard 8 word size clr.w (A0)+ * request to change Turbo ST OFF move.l CONTRL,A0 * get a pointer to the Contrl array move.w #12,(A0)+ * write message through pipe, appl_write() move.w #2,(A0)+ * size of the integer input array clr.w (A0)+ * size of the integer output array move.w #1,(A0)+ * size of the address input array clr.w (A0)+ * size of the address output array move.w TurboId(PC),IntIn * application id of Turbo ST move.w #16,IntIn+2 * size of the message (bytes) move.l #MsgBuff,AddrIn * address of the message buffer move.w AESID,D0 * get the AES indentification code move.l AESPRM,D1 * get a pointer to the AES parameter block trap #2 * call GEM * wait for Turbo ST to turn itself OFF waitMsg move.l CONTROL,A0 * get a pointer to the Contrl array move.w #23,(A0)+ * wait for a message, evnt_mesag() clr.l (A0)+ * size of the IntIn and IntOut arrays move.w #1,(A0)+ * size of the address input array clr.w (A0)+ * size of the address output array move.l #MsgBuff,AddrIn * get a pointer pointer to the message event buffer move.w AESID,D0 * get the AES indentification code move.l AESPRM,D1 * get a pointer to the AES parameter block trap #2 * call GEM cmp.w #$1001,MsgBuff * has Turbo ST responded ? bne.s waitMsg * no, wait for the message event again ***************************************************** * TELL TURBO ST TO TURN ITSELF ON * ***************************************************** * request that Turbo ST turn itself ON lea MsgBuff(PC),A0 * get a pointer to the message buffer move.w #$1000,(A0)+ * turn Turbo ST on or off move.w AppId(PC),(A0)+ * application id of test program clr.w (A0)+ * message is standard 8 word size move.w #1,(A0)+ * request to turn Turbo ST ON move.l CONTRL,A0 * get a pointer to the Contrl array move.w #12,(A0)+ * write message through pipe, appl_write() move.w #2,(A0)+ * size of the integer input array clr.w (A0)+ * size of the integer output array move.w #1,(A0)+ * size of the address input array clr.w (A0)+ * size of the address output array move.w TurboId(PC),IntIn * application id of Turbo ST move.w #16,IntIn+2 * size of the message (bytes) move.l #MsgBuff,AddrIn * address of the message buffer move.w AESID,D0 * get the AES indentification code move.l AESPRM,D1 * get a pointer to the AES parameter block trap #2 * call GEM * wait for Turbo ST to turn itself ON waitMsg move.l CONTROL,A0 * get a pointer to the Contrl array move.w #23,(A0)+ * wait for a message, evnt_mesag() clr.l (A0)+ * size of the IntIn and IntOut arrays move.w #1,(A0)+ * size of the address input array clr.w (A0)+ * size of the address output array move.l #MsgBuff,AddrIn * get a pointer pointer to the message event buffer move.w AESID,D0 * get the AES indentification code move.l AESPRM,D1 * get a pointer to the AES parameter block trap #2 * call GEM cmp.w #$1001,MsgBuff * has Turbo ST responded ? bne.s waitMsg * no, wait for the message event again : : etc : : * the ever present (and disturbing) Gem arrays Contrl ds.w 12 * control array Global ds.w 18 * global array for AES IntIn ds.w 128 * integer input array IntOut ds.w 128 * integer output array PtsIn ds.w 128 * points input array PtsOut ds.w 128 * points output array AddrIn ds.w 128 * address input array AddrOut ds.w 128 * address output array * miscellaneous bits and pieces... AppId ds.w 1 * application id of your program... TurboId ds.w 1 * Turbo ST application id MsgBuff ds.w 16 * message buffer * the AES Parameter Block AesPblk dc.l Contrl * pointer to the Contrl array dc.l Global * pointer to the Global array dc.l IntIn * pointer to the IntIn array dc.l IntOut * pointer to the IntOut array dc.l AddrIn * pointer to the AddrIn array dc.l AddrOut * pointer to the AddrOut array * the name of the Turbo ST application (color desk accessory version) DeskName dc.b "TRBOCOLR",0 * Turbo ST application's name