home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / amiga / misc / mtrd.lha / MTRD.doc < prev    next >
Encoding:
Text File  |  1992-06-13  |  11.6 KB  |  344 lines
  1. *************************************************************************
  2. *                                                                       *
  3. *                 MTRD Library for the Amiga                            *
  4. *                                                                       *
  5. *                   A Programmer's manual                               *
  6. *                                                                       *
  7. *************************************************************************
  8.  
  9. Version 0.99 Beta.
  10. 1992 By Amit Fridman. (Silk).
  11.  
  12. Contents
  13. --------
  14.  
  15.  1. Status.
  16.  2. General Description.
  17.  3. Library Description
  18.   3.1 Data Structures.
  19.   3.2 Function Description.
  20.   3.3 Macros.
  21.  4. Technical Data
  22.   4.1 Command Data Block.
  23.   4.2 File Type & SubType.
  24.   4.3 Compiler notes.
  25.  5. Package Contents.
  26.  
  27.  
  28. 1. Status
  29. ---------
  30.  
  31.   The library and support routines are Public Domain. All non-commercial use
  32.   is permitted. For commercial use contact me.
  33.   If you feel a terrible urge to send me money , don't hesitate!
  34.  
  35.  
  36. 2. General Description
  37. ----------------------
  38.  
  39.  What is MTRD ?
  40.   This library gives all tasks in the system the means for accessing
  41.   a buffer of common data. This buffer can be global or private to every task.
  42.   Further more this data can be dynamically changed and that change would
  43.   be reflected in every task's own buffer.
  44.  
  45. The system has two key components :
  46.   1. File - A File defines a Buffer of data & also describes it's contents.
  47.             The buffer connected with the File is global and can be read
  48.             by all tasks in the system.
  49.             Every File has a special user associated with it - the MasterUser.
  50.             Normally only the MasterUser can write to the buffer , unless the
  51.             File is defined Global.
  52.   2. User - Any Task/Process in the system can register to a File and thus
  53.             have access to that file's buffer. It can also define a private
  54.             buffer which will be updated when the global buffer is changed.
  55.  
  56. A frame of use is as follows:
  57.  
  58.  MasterUser:
  59.   opens a File.
  60.   ...
  61.   writes data to the file.
  62.   ...
  63.   closes the File.
  64.  
  65.  Any other User:
  66.   queries for the available Files.
  67.   finds a suitable file (by Type/SubType or Name).
  68.   joins a File as a User.
  69.   ...
  70.   read data from the MasterUser's buffer.
  71.    or
  72.   read data from it's own private buffer.
  73.   ...
  74.   leaves File
  75.  
  76. ( see mouse.c for an example of MasterUser
  77.   see print.c for an eaample of a regular User )
  78.  
  79.  
  80. 3. Description of Library
  81. -------------------------
  82.  
  83. Following sections define the Data Structures , Functions and Macros
  84. of the Library.
  85.  
  86.  3.1 Data Structures
  87.  -------------------
  88.  
  89. > MtrdBase -- Internal definition of the library *** Private ***
  90.  
  91. > MFile    -- Defines a File. The following fields are of interest :
  92.    struct FileID FID        - Definition of the buffer.
  93.    struct MUser *MasterUser - MasterUser for this file.
  94.    UWORD Flags              - File's flags.
  95.  
  96.     MTFF_PUBLIC - This file is Public (All users can write to it).
  97.  
  98. > MUser    -- Defines a User. Don't mess with any of the fields.
  99.     UWORD Flags              - User's flags. (Use CUSERFLAGS Macro to change).
  100.  
  101.    MUSF_LOCED     - This buffer is locked against updating.
  102.    MUSF_BUFFER    - This user has a private buffer.
  103.    MUSF_NOTIFY    - Let me know when an update has occured.
  104.    MUSF_LOCKWRITE - Lock the buffer after each update. (Use UNLOCK Macro to
  105.                      allow for further updates).
  106.    MUSF_MASTER    - This user is the MasterUser *** Private ***
  107.  
  108. > FileID   -- Define the location , size & contents of a File's buffer.
  109.    UWORD Type     - Defines the type of data in the buffer (see MTRDTypes.h)
  110.    UWORD SubType  - Further defines the type of data and it's format.
  111.    ULONG Size     - Size in bytes of the buffer.
  112.    char *Data     - Pointer to the buffer itself.
  113.    char *Name     - A string identifying this buffer (optional).
  114.    ULONG Defs[4]  - Parameters to define complex types of buffers.
  115.  
  116. > FileList -- A Description of one file in the system.
  117.     struct MFile *File - A Pointer to the specific file.
  118.     UWORD Flags        - That file's flags.
  119.     struct FileID FID  - A description of the buffer's contents.
  120.  
  121. > MUpdate  -- A Message from the system.
  122.    struct MFile *File - The file this message relates to.
  123.    ULONG Type         - Type of message.
  124.  
  125.    MTUP_UPDATE - The message indicates that the user's buffer has been updated.
  126.    MTUP_CLOSE  - The File has been closed.
  127.  
  128.    When recieving any message you should ReplyMsg() it back.
  129.  
  130.  
  131.  3.2 Functions
  132.  -------------
  133.  
  134. The library should first be opened by:
  135.  struct MtrdBase *MtrdBase;
  136.  
  137.  MtrdBase=OpenLibrary("mtrd.library",VERSION); /* VERSION is currently 0 */
  138.  
  139. When exiting close the library with:
  140.  CloseLibrary(MtrdBase);
  141.  
  142.  
  143. > struct MFile *OpenMFile(Port,Fid,Flags)
  144.  
  145.    Opens a new File and adds the caller as the MasterUser for this file.
  146.  
  147.     struct MsgPort *Port - Pointer to MsgPort for recieving messages
  148.                              (may be NULL).
  149.     struct FileID *Fid   - Pointer to the FileID definition for this File.
  150.     UWORD Flags          - File's flags (MTFF_PUBLIC if needed).
  151.  
  152.     Returns              - A Pointer to a MFile if successful or NULL.
  153.  
  154. > void CloseFile(File,User)
  155.  
  156.    Closes a file previously opened by this User. notifies all connected Users
  157.     and unlinks them.
  158.  
  159.     struct MFile *File - The File to be closed.
  160.     struct MUser *User - The MasterUser for this file. (DON'T cheat here).
  161.  
  162. > void WriteData(File,User,Data)
  163.  
  164.    Writes new data to the Global buffer , also updates the local buffers and
  165.     notifies their users.
  166.  
  167.     struct MFile *File - The File who's buffer is to be updated.
  168.     struct MUser *User - The calling user (MasterUser for non-public File).
  169.     char *Data         - A Pointer to a well formatted data block (see 4.1).
  170.  
  171. >>> for the following two functions see also 4.2 <<<
  172.  
  173. > ULONG CountFiles(Type,SubType)
  174.  
  175.    Count the number of files in the system that are of a specific type &
  176.     SubType.
  177.  
  178.     UWORD Type     - Type mask for counted Files (GET_ALL counts all).
  179.     UWORD SubTypes - SubType mask for counted Files (GET_ALL counts all).
  180.  
  181.     Returns        - Number of Files of indicated type.
  182.  
  183. > ULONG GetFileList(FList,Max,Type,SubType)
  184.  
  185.    Fill a set of FileList structures with File definitions according to their
  186.     Type & SubType.
  187.  
  188.     struct FileList *FList - Pointer to array of FileList structures.
  189.     ULONG Max              - Maximum number of entries to fill.
  190.     UWORD Type             - Type mask for Files.
  191.     UWORD SubType          - SubType mask for Files.
  192.  
  193.     Returns                - Actual number of FileList entries.
  194.  
  195. > struct MUser *AddUser(File,Port,Buffer,Flags)
  196.  
  197.    Adds User to an open File. Optionally defines user's private buffer.
  198.  
  199.     struct MFile *File   - The File you wish to join.
  200.     struct MsgPort *Port - A pointer to the MsgPort where messages will be
  201.                              recieved (may be NULL).
  202.     char *Buffer         - A pointer to a private buffer (optionally NULL).
  203.     UWORD Flags          - User's flags. See MUser structure description.
  204.                             (Do not set MUSF_MASTER bit!).
  205.  
  206.     Returns              - A Pointer to MUser if successful , NULL otherwise.
  207.  
  208. > void RemUser(User)
  209.  
  210.    Remove a User from a File.
  211.  
  212.     struct MUser *User - The User to be removed. No need to specify the File.
  213.  
  214. >>> Data Block Functions (see 4.1) <<<
  215.  
  216. > void InitData(block)
  217.  
  218.    Initialize a Command Data Block.
  219.  
  220.     char *block - Pointer to Data Block.
  221.  
  222. > void AddBytes(block,offset,count,ptr)
  223. > void AddWords(block,offset,count,ptr)
  224. > void AddLongs(block,offset,count,ptr)
  225.  
  226.    These functions add another command to the Data Block. They differ in the
  227.     type of data that is used.
  228.  
  229.     char *block  - A Pointer to the Command Data Block.
  230.     ULONG offset - Sets offset from start of Buffer for this command.
  231.     UWORD count  - Number of elements in this command.
  232.     (char/UWORD/ULONG) *ptr - A Pointer to an array of 'count' items used to
  233.                                Update the Buffer.
  234.  
  235. > void AddFill(block,offset,count,fill)
  236.  
  237.    This function adds a fill command to the Data Block. The fill is done with
  238.     UWORDs.
  239.  
  240.     char *block  - A Pointer to the Command Data Block.
  241.     ULONG offset - Sets offset from start of Buffer for this command.
  242.     UWORD count  - How many times to repeat the fill UWORD.
  243.     UWORD fill   - The UWORD to use for the fill.
  244.  
  245.  
  246.  3.3 Macros
  247.  ----------
  248.  
  249. There are several Macros in the MTRD.h file :
  250.  
  251. > GETMUSER(file,user)    : Place a pointer to the MasterUser for this File in
  252.                             user.
  253. > GETFID(file,fid)       : Structure copy the FileID for this File into fid.
  254. > GETBUFFER(file,buffer) : Grab the Global Buffer address from File and place
  255.                             it in buffer.
  256. > CUSERFLAGS(user,flags) : Change the Flags for this User.
  257. > UNLOCK(user)           : Unlock a private buffer.
  258.  
  259.  
  260. 4. Technical Data
  261. -----------------
  262.  
  263.  4.1 Command Data Block
  264.  ----------------------
  265.  
  266.   Updating a buffer is done via a call to WriteData().
  267.   The data is delivered in the Command Data Block. This is a block of memory
  268.   which contains the specific information as to how the buffer should be
  269.   changed. Each Command Data Block can contain several 'sub-blocks' that change
  270.   Different areas of the Buffer. The only limit on the CDB is that it shouldn't
  271.   exceed 64K.
  272.   To change the Buffer do the following :
  273.    InitData() your CDB.  
  274.    do a series of AddBytes(),AddWords(),AddLongs(),AddFill() to set
  275.     different areas of the Buffer.
  276.    Execute a WriteData().
  277.  
  278.   The size of your Data Block should be longer than the amount of data you
  279.   wish to send. To calculate the size use the following scheme :
  280.    4+(6+bytes_of_data)*for_each_sub_block
  281.  
  282.  4.2 File Type & SubType
  283.  -----------------------
  284.  
  285.  The Type field contains the general Type of data stored. (TEXT,GRAPH etc.)
  286.  The SubType field contains a further definition of the type of data (such as
  287.   RELMOUSECOORDS or RAWTEXT) and also the data format (CHAR,FLOAT etc.)
  288.  All Type & SubType definitions are flags , that is they define one bit-field
  289.  and thus can be masked.
  290.  To Request a specific type of File Set the corresponding bits in the request
  291.   parameters Type/SubType. Setting them to GET_ALL (0xFFFF) gets any type of
  292.   File.
  293.  Examples:
  294.   num=CountFiles(GET_ALL,GET_ALL)          ; Count all files in the system.
  295.   num=CountFiles(MTT_TEXT,MTS_CHAR)        ; Count character based Texts.
  296.   num=GetFileList(myFList,4,GET_TABLE,MTS_LONG|MTS_FLOAT|GET_ALLSUB)
  297.                                            ; Read Max 4 Table Files of any 
  298.                                            ; SubType with ULONG or Float
  299.                                            ; data format.
  300.  
  301.  4.3 Compiler Notes
  302.  ------------------
  303.  
  304.  The library was written in C on AztecC V5.2 . (using the myLib demo).
  305.  The pragmas are Aztec compatible so you may have to recode them for other
  306.   compilers.
  307.  
  308.  
  309. 5. Package Contents
  310. -------------------
  311.  
  312. The package contains the following files :
  313.  MTRD.library -- the library itself. Copy it to your LIBS: directory.
  314.  MTRD.fd      -- fd definition file.
  315.  MTRD.h       -- Include file for writing programs that user the library.
  316.  MTRDTypes.h  -- A sample of defined types and sub-types.
  317.  mouse.c      -- A demo of a MasterUser. code.
  318.  mouse        -- Executable for the MasterUser demo.
  319.  print.c      -- A demo of a regular user. code.
  320.  print        -- Executable for the regular user demo.
  321.  MTRD.doc     -- This file.
  322.  
  323. To run the demo programs do the following :
  324.  
  325. * RUN 'mouse'
  326. * RUN 'print'
  327. * Activate the 'mouse' window and move the mouse. You should see the mouse
  328.   coordinates in the 'print' window.
  329. * To quit click the RMB in the 'mouse' window.
  330.  
  331.  
  332.  
  333. **************   That's All Folks!!!  **************
  334.  
  335. Amit Fridman (Silk)
  336.  
  337. EMail:
  338. s2449558@techst02.technion.ac.il
  339.  
  340. SnailMail:
  341. Amit Fridman
  342. Eshkol 15 Yehud
  343. Israel 56000
  344.