home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / reference / amiga_mail_vol1 / dos / newpackets1.2 < prev    next >
Text File  |  1990-01-26  |  11KB  |  282 lines
  1. (c)  Copyright 1989 Commodore-Amiga, Inc.   All rights reserved.
  2. The information contained herein is subject to change without notice, and 
  3. is provided "as is" without warranty of any kind, either expressed or implied.  
  4. The entire risk as to the use of this information is assumed by the user.
  5.  
  6.  
  7.  
  8.  
  9.             NEW PACKETS AND STRUCTURES IN 1.2 AMIGADOS
  10.  
  11.                          Carolyn Scheppner
  12.  
  13.       AmigaDOS contains many features which can only be accessed
  14.    by sending a packet directly to a process.  One example is the
  15.    ACTION_INHIBIT packet which can be sent to the handler process
  16.    of a disk drive to stop the verification which normally occurs
  17.    when disks are inserted.  This packet is used by Diskcopy and
  18.    Format to prevent disk verification and "Not a DOS Disk"
  19.    requestors during the format or backup process.  The packet is
  20.    sent to the MsgPort of a drive's handler.
  21.  
  22.       The handler MsgPort of most named AmigaDOS devices like df0:
  23.    can be found with the DeviceProc() function.  Note that DeviceProc()
  24.    can not be used to find a CON: or RAW: handler because there may be
  25.    many handlers for each of these.  The handler MsgPort (ProcessID)
  26.    of a CON: or RAW: window is in its FileHandle structure (fh_Type).
  27.    The MsgPort of a CLI process's "*" window is process->pr_ConsoleTask.
  28.  
  29.    Here are some examples:
  30.  
  31.    1. port = (struct MsgPort *)DeviceProc("DF1:");
  32.  
  33.    2. fh = Open("CON:0/40/640/140/Test",MODE_NEWFILE);
  34.       port = (struct MsgPort *)(((struct FileHandle *)(fh<<2))->fh_Type);
  35.  
  36.    3. myCliProc = (struct Process *)FindTask(NULL);
  37.       port = myCliProc->pr_ConsoleTask;
  38.  
  39.  
  40.       A struct StandardPacket contains an Exec Message structure
  41.    and an AmigaDOS DosPacket structure.
  42.  
  43.       struct StandardPacket {
  44.          struct Message    sp_Msg;
  45.          struct DosPacket  sp_Pkt;
  46.          };
  47.  
  48.       This combined structure is only used for convenience since
  49.    the DosPacket structure does not have to directly follow the
  50.    Message structure in memory.
  51.  
  52.       The actual linkage between the Message and the Packet are
  53.    pointers in each structure which point to each other.  The
  54.    Message's mn_Node.ln_Name member must be initialized to point
  55.    to the DosPacket, and the Packet's dp_Link field must point
  56.    to the Exec Message.
  57.  
  58.       packet->sp_Msg.mn_Node.ln_Name = (char *)&(packet->sp_Pkt);
  59.       packet->sp_Pkt.dp_Link         = &(packet->sp_Msg);
  60.  
  61.       StandardPacket or DosPacket structures must be longword aligned
  62.    and should be dynamically allocated in any language where such
  63.    alignment can not be specified for variables.  The same is true
  64.    for any structures you are asking DOS to fill, such as the InfoData
  65.    structure initialized via the ACTION_DISK_INFO packet.
  66.  
  67.       struct DosPacket {
  68.          struct Message  *dp_Link;   /* Link to the Exec Message  */
  69.          struct MsgPort  *dp_Port;   /* Reply port for the packet */
  70.          LONG  dp_Type;              /* Packet action number/type */
  71.          LONG  dp_Res1;              /* Return value 1            */
  72.          LONG  dp_Res2;              /* Return value 2            */
  73.          LONG  dp_Arg1;              /* Packet arguments          */
  74.            through
  75.          LONG  dp_Arg7;
  76.          };
  77.  
  78.  
  79.       The Technical Reference portion of the AmigaDOS manual details
  80.    the arguments and usage of most packet types.  There are several
  81.    new packet types in 1.2 AmigaDOS, and an enhancement to the
  82.    existing DiskInfo packet.  Note that the new packet numbers are
  83.    not defined in the libraries/dosextens headers.  You can define
  84.    these new packet numbers in your own code.
  85.  
  86.  
  87.  
  88.          DESCRIPTIONS OF NEW AND ENHANCED DOS PACKET TYPES
  89.  
  90.  
  91.       If your program uses new 1.2 functions or features such as the
  92.    new packets, your code should make sure that it is being run on
  93.    a system booted with at least v1.2.  To do this, specify version
  94.    number 33 in your OpenLibrary() calls and abort gracefully if
  95.    the OpenLibrary() returns NULL.
  96.  
  97.       The Res1 result of most of these packets is BOOLEAN (0L = failure).
  98.    But DiskInfo is documented as always returning TRUE (-1L) and it
  99.    appears that SetRawCon does the same.  
  100.  
  101.    o  SetFileDate ( ACTION_SET_DATE = 34L )
  102.  
  103.       Sets the date of a file or directory to specified date.
  104.       The packet is sent to the MsgPort returned by DeviceProc(filename).
  105.       The args for the packet are:
  106.  
  107.          arg[0] = NULL
  108.          arg[1] = lock on ParentDir of file
  109.          arg[2] = BPTR to BSTR of filename
  110.          arg[3] = APTR to a DateStamp structure
  111.  
  112.       A new CLI command SetDate <file> <date> [<time>] is also provided.
  113.       Note that SetFileDate packet and SetDate command did not work
  114.       properly on either ram or disk files until the release version of 1.2.
  115.  
  116.    o SetRawMode ( ACTION_SCREEN_MODE = 994L )
  117.  
  118.       Switches CON: into raw mode and back again. The single argument
  119.       is DOS TRUE (-1L) for raw mode (as if RAW: had been requested)
  120.       and DOS FALSE (0L) to turn it back to CON: style.  The packet is
  121.       sent to a (struct MsgPort *)process->pr_ConsoleTask.
  122.  
  123.       Note that in addition to this, an escape sequence may be sent
  124.       to turn on or off the automatic translation of LF to CR/LF.
  125.       Normally RAW: does not enable this and CON: does.  SetRawMode
  126.       does not affect the translation.  The escape sequences are
  127.       CSI 20h to enable, and CSI 20l to disable this translation.
  128.  
  129.    o  Flush ( ACTION_FLUSH = 27L )
  130.  
  131.       Cause pending blocks to be written out and motor turned off.
  132.       This is expensive, so should not be done after every write.
  133.       It is used by the system before putting up a requestor saying
  134.       "Change Disk" and the packet is only returned when the job
  135.       is done.  This action would be useful in a database when it
  136.       wished to commit.
  137.  
  138.    o  MoreCache ( ACTION_MORE_CACHE = 18L )
  139.  
  140.       The single argument indicates the number of extra cache buffers
  141.       to be obtained for use.  Used by ADDBUFFERS command.
  142.  
  143.    o  DiskInfo ( ACTION_DISK_INFO = 25L )
  144.  
  145.       When sent to a console handler, this packet now returns not only
  146.       the window pointer in the id_VolumeNode field, but also a pointer
  147.       to the console handler's console IO block in the id_InUse field.
  148.       These fields are part of the InfoData structure initialized by
  149.       ACTION_DISK_INFO.  Remember that you must AllocMem your InfoData
  150.       structure to assure longword alignment since a BPTR to this
  151.       structure is arg[0] for the packet.
  152.  
  153.       A pointer to the ConUnit structure (see devices/conunit.h, .i)
  154.       can be found from the returned console IO block pointer:
  155.  
  156.          conUnit = (struct ConUnit *)
  157.                       ((struct IOStdReq *)infoData->id_InUse)->io_Unit;
  158.  
  159.       There is a lot of useful information in the ConUnit structure
  160.       such as text cursor position and limits.  If you are using the
  161.       Exec console.device directly, you should be able to get the
  162.       ConUnit pointer from yourIoRequest->io_Unit.
  163.  
  164.  
  165.                    EXAMPLE PACKET SENDING FUNCTION
  166.  
  167.  
  168. #include <exec/types.h>
  169. #include <exec/memory.h>
  170. #include <libraries/dos.h>
  171. #include <libraries/dosextens.h>
  172.  
  173. /*
  174.  * sendpkt() by A. Finkel, P. Lindsay, C. Scheppner
  175.  *  returns Res1 of the reply packet
  176.  */
  177.  
  178. LONG sendpkt(pid,action,args,nargs)
  179. struct MsgPort *pid;  /* process indentifier (handler message port) */
  180. LONG action,          /* packet type (desired action) */
  181.      args[],          /* a pointer to a argument list */
  182.      nargs;           /* number of arguments in list  */
  183.    {
  184.    struct MsgPort        *replyport;
  185.    struct StandardPacket *packet;
  186.  
  187.    LONG  count, *pargs, res1;
  188.  
  189.    replyport = (struct MsgPort *) CreatePort(NULL,0);
  190.    if(!replyport) return(NULL);
  191.  
  192.    packet = (struct StandardPacket *)
  193.       AllocMem((long)sizeof(struct StandardPacket),MEMF_PUBLIC|MEMF_CLEAR);
  194.    if(!packet)
  195.       {
  196.       DeletePort(replyport);
  197.       return(NULL);
  198.       }
  199.  
  200.    packet->sp_Msg.mn_Node.ln_Name = (char *)&(packet->sp_Pkt);
  201.    packet->sp_Pkt.dp_Link         = &(packet->sp_Msg);
  202.    packet->sp_Pkt.dp_Port         = replyport;
  203.    packet->sp_Pkt.dp_Type         = action;
  204.  
  205.    /* copy the args into the packet */
  206.    pargs = &(packet->sp_Pkt.dp_Arg1);   /* address of first argument */
  207.    for(count=0;count < nargs;count++)
  208.       pargs[count]=args[count];
  209.  
  210.    PutMsg(pid,packet); /* send packet */
  211.  
  212.    WaitPort(replyport);
  213.    GetMsg(replyport);
  214.  
  215.    res1 = packet->sp_Pkt.dp_Res1;
  216.  
  217.    FreeMem(packet,(long)sizeof(struct StandardPacket));
  218.    DeletePort(replyport);
  219.  
  220.    return(res1);
  221.    }
  222.  
  223.  
  224.                     AMIGADOS 1.2 STRUCTURE CHANGES
  225.                     ==============================
  226.  
  227.    PATH LIST:
  228.       The path list is held as a BPTR in the CommandDir member of the
  229.       CommandLineInterface structure.  Although currently documented
  230.       as the lock on the command directory, this is either 0 or a
  231.       BPTR to a list of path elements, each consisting of:
  232.          BPTR NextPath     (BPTR to next list entry)
  233.          BPTR PathLock     (a lock on the directory)
  234.  
  235.    RESIDENT SEGMENT LIST:
  236.       The resident segment list is held as a BPTR in the DosInfo
  237.       substructure within the global data structure.  The segment
  238.       list replaces the slot currently defined as NetHand, and is
  239.       byte offset 16 from the DosInfo base.  Each entry is:
  240.          BPTR  NextEntry    (BPTR to next list entry)
  241.          LONG  UseCount     (Use count for segment, -1 if unloadable)
  242.          BPTR  SegPtr       (Segment pointer)
  243.          BSTR  SegName      (Segment Name)
  244.  
  245.    DEVINFO STRUCTURE:
  246.       The specification of the DevInfo structure has been expanded.
  247.       The GlobVec member used when the DevInfo refers to a device
  248.       (Type = DLT_DEVICE = 0) is documented as being a global
  249.       vector pointer or 0.  Now this value may be -1 indicating
  250.       that the handler process does not need a global vector and
  251.       should be called as a C process.
  252.  
  253.       The DevInfo structure is described in the AmigaDOS Technical
  254.       reference manual, but does not appear in the dosextens headers.
  255.       It is basically the same as the DeviceList structure described
  256.       in dosextens, with device-specific redefinitions of the fifth
  257.       through tenth longwords in the structure.
  258.  
  259.       struct DevInfo
  260.          {
  261.          BPTR  Next;       /* Next list entry or 0 */
  262.          LONG  Type;       /* Entry Type (0=device,1=dir,2=vol ?) */
  263.          APTR  Task;       /* Handler process msgport or 0 */
  264.          BPTR  Lock;       /* File system lock or 0 */
  265.          BSTR  Handler;    /* File name of handler or 0 */
  266.          LONG  Stacksize;  /* Stack size for handler process */
  267.          LONG  Priority;   /* Priority for handler process */
  268.          LONG  Startup;    /* Startup value passed to handler */
  269.          BPTR  SegList;    /* SegList for handler process or 0 */
  270.          BPTR  GlobVec;    /* Global vector, or 0, or - 1 */
  271.          BSTR  Name;       /* Name of device or ASSIGN'd name */
  272.          };
  273.  
  274.       The AmigaDOS device list can be found from DosBase.
  275.          dl =  (struct DosLibrary *)DosBase;
  276.          rn =  (struct RootNode *)dl->dl_Root;
  277.          di =  (struct DosInfo *)BADDR(rn->rn_Info);
  278.          dev = (struct DevInfo *)BADDR(di->di_DevInfo);
  279.  
  280.  
  281.  
  282.