home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / wps / com / zocdev / tap / tech.doc < prev   
Encoding:
Text File  |  1993-12-02  |  5.9 KB  |  210 lines
  1.  
  2.     This document discusses technical matters of the TAPs described
  3.     in ABSTRACT.DOC. No (C) of any kind applies - implementation of
  4.     TAP in clients or terminals is free. 
  5.     
  6.     However sole host of truth about the TAP interface is me. If you 
  7.     have any ideas for improvement (or need other events for your TAP)
  8.     let me know. 
  9.  
  10.     If you plan to implement the terminal side of the TAP interface
  11.     contact me for sample sources.
  12.  
  13.  
  14.     Keep OS/2 interesting for the people, develop for OS/2!!!
  15.  
  16.  
  17.  
  18.     Markus Schmidt
  19.  
  20.  
  21.  
  22.     
  23.  
  24.     Introduction:
  25.     =============
  26.  
  27.     Each TAP is an independent EXE file with the Name TAP_XXX.EXE
  28.     where XXX is a file extension or the text 'ALL'. A TAP is
  29.     designed to listen to file events occuring in an up- or
  30.     download. Normally a TAP is designed to understand only files of
  31.     a specific type such as GIF or ZIP. 
  32.  
  33.     A TAP provides a special service while up- or downloading such as  
  34.  
  35.     o  online picture viewing (as the TAP_GIF.EXE delivered 
  36.        with ZOC) 
  37.  
  38.     o  online archive unpacking 
  39.  
  40.     o  virus scanner for downloaded files 
  41.  
  42.     o  nice up-/download progress indicators, speedometers, 
  43.  
  44.        or logging facilities 
  45.  
  46.     o  an nice end of transfer bell for your soundblaster 
  47.  
  48.     o  leisure games to spend transfer time more usefully 
  49.  
  50.     
  51.  
  52.     Starting your TAP application:
  53.     ==============================
  54.  
  55.     As you see there are file specific and non file specific TAPs.
  56.     Whenever a file is opened during a transfer ZOC will try to find
  57.     all TAPs running at this time.
  58.     If there are none and the 'Start taps' option is enabled, ZOC will 
  59.     try to start a TAP that matches the extension of the incoming file.
  60.     If no such TAP exists ZOC will try to find a TAP called TAP_ALL.EXE. 
  61.     It is not an error if no TAPs exist at all.
  62.  
  63.     
  64.  
  65.     Method of communication:
  66.     ========================
  67.  
  68.     Queues are used for communication between ZOC and the TAP. The
  69.     queue is opened by the TAP and ZOC puts messages into that
  70.     queue. If the TAP cannot create the queue it is very likely that
  71.     another TAP is already running. In this case the TAP should try to
  72.     another queue name (see 'Queue Names') or exit.
  73.  
  74.  
  75.         // simple example of how to open a tap queue
  76.         HQUEUE hq= 0;
  77.         DosCreateQueue(&hq, QUE_FIFO, TAP_QUEUE_NAME);
  78.         if (hq) {
  79.             // process messages
  80.         }
  81.         else {
  82.             // exit gracefully
  83.         }
  84.  
  85.  
  86.  
  87.     Incoming messages are read like this:
  88.  
  89.  
  90.  
  91.         REQUESTDATA rqd;
  92.         ULONG length;
  93.         VOID *data;
  94.         BYTE prio;
  95.  
  96.         DosReadQueue(hq, 
  97.             &rqd,           // ulData-field for eventcode
  98.             &length,        // field for data length or offset
  99.             &data,          // field for data pointer
  100.             0,              // get first element from queue
  101.             0,              // wait synchronously for data
  102.             &prio,          // element priority (unused)
  103.             0);             // no semaphore
  104.  
  105.     The structure rqd receives an eventcode in its ulData field. 
  106.     The following eventcodes exist (as defined in TAP.H):
  107.  
  108.  
  109.  
  110.         Download events:
  111.         TAP_EVENT_OPENFORWRITE
  112.         TAP_EVENT_OPENFORAPPEND
  113.         TAP_EVENT_WRITEBLOCK
  114.  
  115.         Upload events:
  116.         TAP_EVENT_OPENFORREAD
  117.         TAP_EVENT_READBLOCK
  118.         TAP_EVENT_READBYTE
  119.         TAP_EVENT_SEEK
  120.  
  121.         Up-/Download events:
  122.         TAP_EVENT_CLOSE
  123.         TAP_EVENT_HOSTINFO
  124.  
  125.  
  126.     The following table describes the parameters for the events:
  127.  
  128.  
  129.  
  130.        EVENT          DATA-PTR                LENGTH-FIELD
  131.  
  132.        OPENFORREAD    filename '\0' size '\0' strlen(Filename)+1+7+1
  133.  
  134.        OPENFORWRITE   filename '\0' size '\0' strlen(Filename)+1+7+1
  135.  
  136.        OPENFORAPPEND  filename '\0' size '\0' strlen(Filename)+1+7+1
  137.  
  138.        READBLOCK      ptr to copy of          length of data 
  139.                       read data
  140.  
  141.        WRITEBLOCK     ptr to copy of          length of data 
  142.                       written data
  143.  
  144.        READBYTE       (UCHAR)byte of data     1
  145.  
  146.        SEEK           NULL                    new seek position
  147.  
  148.        CLOSE          NULL                    0
  149.  
  150.        HOSTINFO       ptr to TAP_HOSTINFO     sizeof(HOSTINFO)
  151.                       struct
  152.  
  153.  
  154.  
  155.     Other events might be received (most likely from a future
  156.     version of ZOC) and should be ignored. 
  157.  
  158.     If a data pointer exists it points to a block of giveable memory
  159.     and has to be freed by DosFreeMem()
  160.  
  161.     Check TAP.C for source code of how to access the filesize.
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.     Queue Names:
  169.     ============
  170.     The name of the communication queue is defines in TAP.H as 
  171.  
  172.         #define TAP_QUEUE_NAME "\\QUEUES\\ZOC\\TRANSFER.TAP\\A"
  173.  
  174.     This is the default queue name. To run more than one TAP at a 
  175.     time unique names are necessary for each TAP. To create such a 
  176.     name, the TAP may increment the last character of the name and
  177.     try to open the queue again (but not more often than TAP_MAX
  178.     times). 
  179.     I recommend to use this piece of code (from TAP2.C) to find a
  180.     free name:
  181.  
  182.          
  183.         // define a dynamic que name and a que handle
  184.         char szQueName[]= TAP_QUEUE_NAME;
  185.         HQUEUE hq= 0;
  186.  
  187.         // Find a free name and create a data queue to receive info
  188.         for (i= 0; i<TAP_MAX && hq==0; i++) {
  189.             DosCreateQueue(&hq, QUE_FIFO, szQueName);
  190.             szQueName[strlen(szQueName)-1]++;
  191.         }
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.     Example Programs:
  199.     =================
  200.  
  201.     This directory contains two example programs. 
  202.  
  203.     TAP.C is a simple dump utility to show how a queue is opened and
  204.     how events are read from the queue.
  205.  
  206.     TAP2.C shows how to interface the queue more file like and read
  207.     data sequentially byte by byte from it. This might be a good
  208.     place to start to develop your own TAP application. 
  209.  
  210.