home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 240.lha / PickPacket_v1.0 / PickPack.Doc < prev    next >
Text File  |  1989-05-04  |  12KB  |  208 lines
  1. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *\
  2. * |_o_o|\\ Copyright © 1989 The Software Distillery.                      *
  3. * |. o.| ||          All Rights Reserved.                                 *
  4. * | .  | ||          Written by John Toebes and Doug Walker               *
  5. * | o  | ||          The Software Distillery                              *
  6. * |  . |//           235 Trillingham Lane                                 *
  7. * ======             Cary, NC 27513                                       *
  8. *                    BBS:(919)-471-6436                                   *
  9. *      BIX: JTOEBES, DWALKER                                              *
  10. *    PLINK: JTOEBES, DWALKER                                              *
  11. *   Usenet: ...mcnc!rti!sas!(toebes|walker)                               *
  12. *      CI$: sorry, charlie...                                             *
  13. \* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  14.  
  15. ------------------------------COPYRIGHT NOTICE
  16.  
  17. PickPacket is Copyright © 1989 The Software Distillery.  See the file
  18. README.PP for distribution information.
  19.  
  20. ------------------------------DISCLAIMER
  21.  
  22. Neither The Software Distillery nor any of its members will be liable for 
  23. any damage arising from the failure of this program to perform as described,
  24. or any destruction of other programs or data residing on a system 
  25. attempting to run the program.  While we expect no damaging errors, the 
  26. user of this program uses it at his or her own risk.
  27.  
  28. --------------------------------------------------------------------------
  29.  
  30. PICKPACKET - EXPLORING THE PACKET INTERFACE TO AMIGADOS
  31.  
  32. (The concepts discussed here are covered in much greater detail in an
  33.  article in 'Transactor for the Amiga', May 1989 issue.)
  34.  
  35. We first had the idea to write this program while working on a file system
  36. for AmigaDOS.  It turned out that we were writing lots of tiny little C
  37. programs that sent a particular packet to our file system.  Once we had
  38. decided to write it, however, we saw that it would be a useful tool for
  39. new programmers to explore the packet interface to DOS.  We hope you will
  40. enjoy it!
  41.  
  42. AmigaDOS handlers and file systems communicate with application programs
  43. via Messages and MsgPorts, just like most other Amiga system-level tasks do.
  44. There is a handler or file system in charge of every device you have on
  45. your Amiga, from df0: and ram: to ser: and par:.  When you call a function
  46. in dos.library such as Open() or Lock(), dos.library determines which
  47. handler to call and sends it the appropriate packet to do the requested 
  48. action.  If this explanation doesn't make sense to you, try reading the
  49. description of the packet interface in Amiga Transactor, May 1989, or in
  50. the AmigaDOS Technical Reference Manual (part of the AmigaDOS manual by
  51. Bantam Books).
  52.  
  53. PickPacket gives a visual display of the DosPacket structure that is sent
  54. to the handlers and lets you see the results.  You can actually open files,
  55. read and write data, Examine() and ExNext() locks, and so forth, all by 
  56. talking directly to the file system involved from PickPacket.
  57.  
  58.  
  59. ------------------------------GETTING STARTED
  60.  
  61. To run PickPacket, either double-click on its icon or type "PickPacket"
  62. from the CLI.  From the CLI, you can optionally specify an initial device,
  63. as in "PickPacket RAM:".  The default initial device is df0:, but you can
  64. select a different one once inside the program.
  65.  
  66. ------------------------------THE PICKPACKET WINDOW
  67.  
  68. The PickPacket window has many interesting little gadgets and areas.
  69. The dp_Type field contains the packet type of the packet you are working on.
  70. You can select new packet types from the menus, or you can cycle through
  71. the list of packet types by clicking on the left or the right of the data
  72. field for dp_Type.
  73.  
  74. Below the dp_Type field are four lines for dp_Arg1, dp_Arg2, dp_Arg3 and
  75. dp_Arg4.  These four fields correspond to the four possible arguments that
  76. you can pass to a file system.  They contain different values depending on
  77. what packet type you have selected.  A short description of the type of
  78. argument required in that field for that packet type is listed on the
  79. right of the data field.  The box on the right of each dp_Arg field is
  80. a string gadget that contains the value of that field at the moment.  The
  81. box on the left (with the name "dp_Arg?" in it) is a boolean gadget.  You
  82. can use the dp_Arg gadgets to enter values into the string gadgets, as
  83. will be described below.
  84.  
  85. Below the four dp_Arg fields are two dp_Res fields.  These fields will show
  86. the results of the packet you have sent.  Most packets return DOSTRUE in
  87. dp_Res1 to indicate success and DOSFALSE in dp_Res1 to indicate failure.
  88. If the packet failed, dp_Res2 contains the error code indicating why.  If
  89. it succeeded, dp_Res2 SHOULD BE IGNORED.  Some handlers fill it in with
  90. an error code EVEN IF THE PACKET SUCCEEDS.  Exceptions to the DOSTRUE/
  91. DOSFALSE rule are the ACTION_READ and ACTION_WRITE packets, which return
  92. the number of bytes read or written if successful and -1 for an error.
  93.  
  94. In the upper left-hand corner is a gadget labeled "Device".  If you started
  95. PickPacket from the CLI and specified a device, that device name will be
  96. in the string gadget;  otherwise, it will say "df0:".  The device listed
  97. is the one that will receive your packets.  To change it, click on the 
  98. device name and type in a new one.
  99.  
  100. Immediately to the right of the device gadget is the "Send Packet" gadget.
  101. When you click here, PickPacket transmits your packet to the device.  
  102. PickPacket does some validation of the arguments in the dp_Arg fields, but
  103. it is VERY easy to crash your system by sending invalid or nonsense data
  104. to a handler!!!!
  105.  
  106. The four gadgets to the right of the "Send Packet" gadget allocate various
  107. data structures you will need to do some of the more interesting packets.
  108. "Allocate HANDLE" allocates a FileHandle structure;  you will need a 
  109. FileHandle structure to open files for read or write.  "Allocate INFODATA"
  110. allocates a struct InfoData, which is used to get information about a disk
  111. or volume mounted on a handler.  "Allocate FILEINFO" is used to allocate
  112. a FileInfoBlock, which is passed to get information about a file or
  113. directory.  "Allocate BUFFER" is used to allocate a data buffer to read
  114. into or write from.  Any time you allocate a data structure, a new window
  115. representing that data structure will pop up.  One additional window that
  116. may pop up is the Lock window;  when you do a Lock, the file system 
  117. allocates the lock structure on your behalf.  Therefore, the only way to
  118. get a Lock window is to send an ACTION_LOCATE_OBJECT packet to a handler.
  119.  
  120. ------------------------------KNOWING THE PLAYERS
  121.  
  122. The descriptions to the right of the dp_Arg fields can ask for several
  123. different types of objects.  A short description of each follows.  You 
  124. may need to look at a more detailed reference guide (Transactor or the
  125. AmigaDOS manual) to determine what arguments are actually needed.
  126.  
  127. FileLock   - A FileLock is a structure allocated on your behalf when you 
  128.              pass an ACTION_LOCATE_OBJECT to the handler.  NULL is a valid 
  129.              Lock, however, and it indicates the root of the file system.  
  130.              The first ACTION_LOCATE_OBJECT you do, therefore, will pass in
  131.              a NULL lock and the full pathname of the object to lock.  You 
  132.              can specify a NULL lock by selecting NULL from the "Constants"
  133.              menu, then clicking on the appropriate dp_Arg button on the 
  134.              left side of the screen.
  135.  
  136. STRING     - A STRING usually means the packet wants a filename.  If a
  137.              FileLock is also asked for in the same packet, the Lock should
  138.              be a lock on a directory, and the STRING should be a filename
  139.              relative to that directory.  For example, if you have a Lock 
  140.              on df0:c, you could Lock df0:c/dir by sending the lock on 
  141.              df0:c and a relative pathname of "dir".  One exception to the 
  142.              filename rule is in an ACTION_SET_COMMENT packet, where the 
  143.              second STRING asked for is the comment desired.
  144.  
  145. Integer    - An Integer field is to contain some kind of integer constant.
  146.              When doing Reads and Writes, an Integer indicates how many 
  147.              bytes to read or write;  when Locking or Opening files, it 
  148.              contains a constant from the "Constants" menu.  In particular,
  149.              the ACTION_LOCATE_OBJECT packet wants a constant SHARED_LOCK 
  150.              or EXCLUSIVE_LOCK, and the ACTION_FINDINPUT, ACTION_FINDOUTPUT
  151.              and ACTION_FINDUPDATE packets (to open files) want a constant
  152.              ACCESS_READ or ACCESS_WRITE.  To enter a constant, select it
  153.              from the "Constants" menu, then click on the appropriate
  154.              dp_Arg button.
  155.  
  156. FileHandle - A FileHandle field should point to a struct FileHandle.  You
  157.              can allocate a struct FileHandle by clicking on the "Allocate
  158.              HANDLE" button in the main window, or by selecting the menu
  159.              item.  Once a FileHandle window is active, you can enter it
  160.              into the appropriate dp_Arg field by clicking on the window,
  161.              then clicking on the dp_Arg button on the left of the main
  162.              window.  You may also type the name of the window directly
  163.              by clicking into the argument data area and typing.
  164.  
  165. fh_Arg1    - Many packets require the fh_Arg1 field from an open FileHandle
  166.              to do their stuff.  The ACTION_READ, ACTION_WRITE and 
  167.              ACTION_END packets are examples.  Click on the FileHandle
  168.              window, then on the dp_Arg button to set this up.
  169.  
  170. Data Buffer- Allocate a data buffer with the "Allocate BUFFER" button.
  171.              You can set up a dp_Arg field to use the buffer by clicking on
  172.              the data buffer window, then on the appropriate dp_Arg button.
  173.              If the packet also requires a size (as in ACTION_READ and 
  174.              ACTION_WRITE), you can click on the data buffer window and 
  175.              then the dp_Arg field for the integer and the length of the 
  176.              buffer will be filled into the field for you.  (If you want
  177.              to read or write less than the length of the buffer, just
  178.              type the value in to the field.)
  179.  
  180. FileInfoBlock- Allocate a FileInfoBlock with the "Allocate FILEINFO" button.
  181.              You can set up a dp_Arg field to use it by clicking on its 
  182.              window, then on the appropriate dp_Arg button.
  183.  
  184. InfoData   - Allocate an InfoData with the "Allocate INFODATA" button.
  185.              You can set up a dp_Arg field to use it by clicking on its 
  186.              window, then on the appropriate dp_Arg button.
  187.  
  188. BOOLEAN    - BOOLEAN values should be a constant DOSTRUE or DOSFALSE.
  189.              Select the appropriate constant from the "Constants" menu,
  190.              then click on the dp_Arg button for the field you want to
  191.              enter the constant.
  192.  
  193.  
  194. ------------------------------DANGER!! Will Robinson.. DANGER!!
  195.  
  196. When using PickPacket, you are messing around with some low-level DOS 
  197. functionality.  Handlers expect valid values in their argument fields.
  198. YOU CAN AND WILL CRASH YOUR MACHINE IF YOU SEND THE WRONG THING.  For
  199. example, one excellent way of crashing the system is to open a file
  200. on device df0: and pass the FileHandle to RAM: with an ACTION_WRITE
  201. packet.  PickPacket checks some things, but in general, you need to be
  202. careful to send reasonable values, just as you would if you were writing
  203. a program to send the packets yourself.  (Note, see disclaimer above!!!)
  204. In particular, sending two ACTION_END packets for the same handle to the
  205. Fast File System may cause you to have to revalidate the hard disk.
  206.  
  207. How many ways can you think of to trash your machine ?
  208. Meditate on it for a while...