Exchange protocol

1. The command line
    Parameter given when launching a module is a Pascal string (1 byte describing the length of the line, the data-characters, and the null-byte terminator). Data is structured like this:
    • 8 characters corresponding to the application which has called the module. This 8 characters will be given with no transformation to the APPL_FIND function.
      If Joe is the caller, then the 8 characters are:
      "JOE     "
    • The next characters (to the ending null-byte) describe a filename, the HTML file the caller is editing.

    The module should get the first 8 characters of the command line, and APPL_FIND. If there's an error or the caller doesn't exist, the module should not take the rest of the line or consider the command line does not apply to Joe's exchange protocol.


2. Singletasking mode

    The module, before quitting, saves the tag or whatever data for the caller, into the clipboard. Joe accepts *.HTM (text with all lines terminated by LF+CR) and *.STG (C string format, considered as a macro, so you can use "|" and "~") files. Therefore SCRAP.HTM or SCRAP.STG. When quitting, the module returns a value (QUIT ret&):
    • If 0: the caller loads nothing
    • If 1: the caller loads SCRAP.HTM
    • If 2: the caller loads SCRAP.STG
    • If else: not yet supported
    You can return for other callers than Joe other values. Please tell me about what values you have added to normalize this.


3. Multitasking mode

    NB: this applies also for accessories in singletasking mode.

    Joe supports the VA_START message as well as the Drag and Drop protocol.

    The exchanges with modules use the GEM pipe ("Tube GEM" in French). The following decribes the calls. X_adr% is a 16 bytes buffer, mem% is a buffer located in the global memory (X_mem%=GEMDOS(68,L:len%,W:32)) if possible (else: GEMDOS(72,...). 16 bytes buffers are managed by EVNT_MULTI.

  • SEND TEXT TO THE CALLER
    caller_id&=APPL_FIND("????????")
    ' "????????" is the 8 character string read into the command line.
    IF caller_id&>0
      INT{module_adr%}=20140
      INT{module_adr%+2}=module_id&
      INT{module_adr%+4}=0
      INT{module_adr%+6}=0
      INT{module_adr%+8}=0
      INT{module_adr%+10}=format&
      ' (1=*.HTM or *.TXT, 2=*.STG, 0 or else=Joe reads nothing)
      LONG{module_adr%+12}=module_mem%
      ' (address in the global memory where the module has put the text)
      ~APPL_WRITE(caller_id&,16,module_adr%)
    ENDIF
    
    When reading this in his 16 bytes buffers, the caller will or will not read the memory, and respond to the module with:


  • CALLER RESPOND TO MODULE, TEXT RETRIEVED
    module_id&=INT{caller_adr%+6}
    INT{caller_adr%}=20141
    INT{caller_adr%+2}=caller_id&
    INT{caller_adr%+4}=0
    INT{caller_adr%+6}=0
    INT{caller_adr%+8}=0
    INT{caller_adr%+10}=0
    INT{caller_adr%+12}=0
    INT{caller_adr%+14}=0
    ~APPL_WRITE(module_id&,16,caller_adr%)
    


    To facilite the manipulation of the entire file edited by the caller, the module can ask to the caller an automatic save of the text:

  • REQUEST AUTOMATIC SAVE TO CALLER

    caller_id&=APPL_FIND("????????")
    ' "????????" is the 8 character string read into the command line.
    IF caller_id&>0
      INT{module_adr%}=20142
      INT{module_adr%+2}=module_id&
      INT{module_adr%+4}=0
      INT{module_adr%+6}=0
      INT{module_adr%+8}=0
      INT{module_adr%+10}=0
      INT{module_adr%+12}=0
      INT{module_adr%+14}=0
      ~APPL_WRITE(caller_id&,16,module_adr%)
    ENDIF
    
    The caller will save its data and tell next the module it's done, give the address buffer of filename, and the handle of the window if not iconified and existing:


  • CALLER RESPOND TO MODULE, (OWN DATA SAVED) AND INFORMATION
    module_id&=INT{caller_adr%+6}
    INT{caller_adr%}=20144
    INT{caller_adr%+2}=caller_id&
    INT{caller_adr%+4}=0
    INT{caller_adr%+6}=window_handle_of_caller&
    INT{caller_adr%+8}=0
    INT{caller_adr%+10}=0
    LONG{caller_adr%+12}=caller_mem%
    ' the caller has put the filename in a 256 bytes buffer, in global memory.
    ' The filename buffer is permanent, so the module has no need to respond
    ' to the caller. But the module must ask the caller the address
    ' filename: the caller may quit, clean his memory and not respond.
    ~APPL_WRITE(module_id&,16,caller_adr%)
    
    Be carefull with the window handle: it's given to close or shadow the caller window to avoid caller data manipulation during module computing. DO NOT WIND_SET or whatever else the caller window directly, use GEM pipe and fill the 16 bytes buffer as the Screen manager does.
    You can freeze and unfreeze the caller if you know how to do it (See MagiC developer's documention).

    In some cases, you don't need the caller data to be saved. You just only want information, so:

  • REQUEST INORMATION TO CALLER
    caller_id&=APPL_FIND("????????")
    ' "????????" is the 8 character string read into the command line.
    IF caller_id&>0
      INT{module_adr%}=20143
      INT{module_adr%+2}=module_id&
      INT{module_adr%+4}=0
      INT{module_adr%+6}=0
      INT{module_adr%+8}=0
      INT{module_adr%+10}=0
      INT{module_adr%+12}=0
      INT{module_adr%+14}=0
      ~APPL_WRITE(caller_id&,16,module_adr%)
    ENDIF
    
    The caller will respond to the module with the same message if there was an automatic save. Therefore with the 20144 code, the window handle, and the data filename in the caller buffer.