development/compilers/freepascal/rtl/os2/moncalls.pas

   1 {Set tabsize to 4.}
   2 {****************************************************************************
   3
   4   $Id$
   5
   6                            MONCALLS interface unit
   7                      Free Pascal Runtime Library for OS/2
   8                    Copyright (c) 1999-2000 by Florian Kl„mpfl
   9                     Copyright (c) 1999-2000 by Daniel Mantione
  10                       Copyright (c) 1999-2000 by Tomas Hajny
  11
  12  The Free Pascal runtime library is distributed under the Library GNU Public
  13  License v2. So is this unit. The Library GNU Public License requires you to
  14  distribute the source code of this unit with any product that uses it.
  15  Because the EMX library isn't under the LGPL, we grant you an exception to
  16  this, and that is, when you compile a program with the Free Pascal Compiler,
  17  you do not need to ship source code with that program, AS LONG AS YOU ARE
  18  USING UNMODIFIED CODE! If you modify this code, you MUST change the next
  19  line:
  20
  21  <This is an official, unmodified Free Pascal source code file.>
  22
  23  Send us your modified files, we can work together if you want!
  24
  25  Free Pascal is distributed in the hope that it will be useful,
  26  but WITHOUT ANY WARRANTY; without even the implied warranty of
  27  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  28  Library GNU General Public License for more details.
  29
  30  You should have received a copy of the Library GNU General Public License
  31  along with Free Pascal; see the file COPYING.LIB.  If not, write to
  32  the Free Software Foundation, 59 Temple Place - Suite 330,
  33  Boston, MA 02111-1307, USA.
  34
  35 ****************************************************************************}
  36
  37 unit MonCalls;
  38
  39 { Interface library to MONCALLS.DLL (through EMXWRAP.DLL)
  40
  41 Please, note, that monitors are supported for OS/2 v2.1 and above only
  42 (not for v2.0) and that they cannot be used in PM applications.
  43
  44 Changelog:
  45
  46     People:
  47
  48         TH - Tomas Hajny
  49
  50     Date:           Description of change:              Changed by:
  51
  52      -              First released version 1.0          TH
  53
  54 Coding style:
  55
  56     I have tried to use the same coding style as Daniel Mantione in unit
  57     DOSCALLS, although I can't say I would write it the same way otherwise
  58     (I would write much more spaces myself, at least). Try to use it as well,
  59     please. Original note by Daniel Mantione follows:
  60
  61
  62     It may be well possible that coding style feels a bit strange to you.
  63     Nevertheless I friendly ask you to try to make your changes not look all
  64     to different. To make life easier, set your IDE to use tab characters,
  65     turn optimal fill, autoindent and backspace unindents on and set a
  66     tabsize of 4.}
  67
  68 {***************************************************************************}
  69 interface
  70 {***************************************************************************}
  71
  72 uses    Strings;
  73
  74 {$IFDEF FPC}
  75     {$PACKRECORDS 1}
  76 {$ENDIF FPC}
  77
  78 const
  79 {return codes / error constants (those marked with * shouldn't occur)}
  80     No_Error                        =     0;
  81     Error_Not_Enough_Memory         =     8;
  82     Error_Open_Failed               =   110;
  83     Error_Monitors_Not_Supported    =   165;
  84     Error_Mon_Invalid_Parms         =   379;
  85     Error_Mon_Invalid_DevName       =   380;
  86     Error_Mon_Invalid_Handle        =   381;
  87     Error_Mon_Buffer_Too_Small      =   382;
  88     Error_Mon_Buffer_Empty          =   383;
  89     Error_Mon_Data_Too_Large        =   384;
  90     Error_Mon_Bad_Buffer            =   730; {*}
  91     Error_Mon_Chain_Handle          = 32784; {*}
  92     Error_Mon_Not_Registered        = 32785; {*}
  93
  94 {WaitFlag}
  95     IO_Wait     =0; {The monitor thread that issues DosMonRead wishes to block}
  96                     {until a data record is available in its input buffer.}
  97     IO_NoWait   =1; {The monitor thread that issues DosMonRead does not wish}
  98                     {to block when its input buffer is empty.}
  99
 100
 101 {Terminate character device monitoring.  All monitor buffers associated with
 102 this process are flushed and closed.}
 103 {MonHandle - device handle returned from a previous DosMonOpen call.}
 104 {Possible return codes:
 105     0         No_Error
 106     381       Error_Mon_Invalid_Handle}
 107 {Remarks:
 108 * A single process may register one or more monitors with a character device
 109   using the same device handle returned from a previous DosMonOpen call.
 110   When DosMonClose is issued for a specific, opened device handle, all
 111   monitors for the current process registered with this handle terminate.
 112 * When DosMonClose is issued, the monitor loses access to the device data
 113   stream. Before issuing DosMonClose, monitor threads calling DosMonRead and
 114   DosMonWrite should be terminated. After DosMonClose has been called,
 115   DosMonRead calls return an ERROR_MON_BUFFER_EMPTY return code and
 116   DosMonWrite calls return an ERROR_NOT_ENOUGH_MEMORY return code.
 117 * Data area containing monitor buffers should not be freed until after
 118   DosMonClose is called. If data area containing monitor buffers is freed
 119   before DosMonClose is called, a GP fault occurs when DosMonClose is called
 120   and the process is terminated.
 121 * For a detailed description of this call see the chapter "Character Device
 122   Monitors" in the IBM Operating System/2 Version 1.2 I/O Subsystems And
 123   Device Support Volume 1.}
 124 function DosMonClose(MonHandle:word):word; cdecl;
 125
 126 {Gain access to a character device data stream.}
 127 {DevName - device name, monitor handle returned in MonHandle.}
 128 {Possible return codes:
 129     0         No_Error
 130     110       Error_Open_Failed
 131     379       Error_Mon_Invalid_Parms
 132     380       Error_Mon_Invalid_DevName}
 133 {Remarks:
 134 * Only one DosMonOpen call is necessary per device per process. That is,
 135   several DosMonReg calls can be made using the same monitor handle to the
 136   same device. This allows monitors to be registered using different values
 137   for Index from the same process and going to the same device. When the
 138   DosMonClose is issued, all of the monitors registered on the handle are
 139   closed.
 140 * For a detailed description of this call see the chapter "Character Device
 141   Monitors" in the IBM Operating System/2 Version 1.2 I/O Subsystems And
 142   Device Support Volume 1.}
 143 function DosMonOpen(DevName:PChar;var MonHandle:word):word; cdecl;
 144 function DosMonOpen(DevName:string;var MonHandle:word):word;
 145
 146 {Wait for a data record, move it from the input buffer of a registered
 147 character device monitor and place it in a private data area where the monitor
 148 can freely access it.}
 149 {InBuf - monitor input buffer, WaitFlag - see IO_WAIT and IO_NOWAIT constants,
 150 DataBuf - data area in the calling process address space that the data from the
 151 monitor's input buffer is read into, ByteCount - on input size of the DataBuf,
 152 on return number of bytes of data moved.}
 153 {Possible return codes:
 154     0         No_Error
 155     379       Error_Mon_Invalid_Parms
 156     382       Error_Mon_Buffer_Too_Small
 157     383       Error_Mon_Buffer_Empty}
 158 {Remarks:
 159 * For a detailed description of this call see the chapter "Character Device
 160   Monitors" in the IBM Operating System/2 Version 1.2 I/O Subsystems And
 161   Device Support Volume 1.}
 162 function DosMonRead(var InBuf;WaitFlag:word;var DataBuf;
 163                                                var ByteCount:word):word; cdecl;
 164
 165 {Establish an input and output buffers to monitor an I/O stream for a character
 166 device.}
 167 {MonHandle - device handle returned from a previous DosMonOpen call, InBuf -
 168 monitor input buffer, the monitor dispatcher moves data records into this
 169 buffer from the device driver (if the monitor is the first one in the monitor
 170 chain) or from the previous monitor in the chain, monitor then takes data from
 171 this buffer for filtering by calling DosMonRead, OutBuf - monitor output
 172 buffer, monitor places filtered data into this buffer by calling DosMonWrite,
 173 the monitor dispatcher moves data records from this buffer to the device driver
 174 (if the monitor is the last one in the monitor chain) or to the next monitor in
 175 the chain, PosCode - used to specify placement of a monitor's buffers with the
 176 monitor chain (FIRST, LAST or DEFAULT) and whether one or two threads are
 177 created by the monitor dispatcher to handle data movement (see explanation
 178 bellow), Index - device specific value, for the keyboard it pertains to the
 179 session you wish to register a monitor on, for the printer it pertains to the
 180 data or code page monitor chain.}
 181 {Possible return codes:
 182     0         No_Error
 183     8         Error_Not_Enough_Memory
 184     165       Error_Monitors_Not_Supported
 185     379       Error_Mon_Invalid_Parms
 186     381       Error_Mon_Invalid_Handle
 187     382       Error_Mon_Buffer_Too_Small}
 188 {Remarks:
 189 * PosCode meaning:
 190     0   DEFAULT (no position preference) and one thread for data movement
 191     1   FIRST (monitor placed at beginning of monitor chain) and one thread for
 192         data movement
 193     2   LAST (monitor placed at the end of monitor chain) and one thread for
 194         data movement
 195     3   DEFAULT with two threads for data movement
 196     4   FIRST with two threads for data movement
 197     5   LAST with two threads for data movement
 198   The first monitor in a monitor chain that registers as FIRST is placed at the
 199   head of the monitor chain. The next monitor that registers as FIRST follows
 200   the last monitor registered as FIRST, and so on. Similarly, the first monitor
 201   that registers as LAST is placed at the end of the monitor chain. The next
 202   monitor that registers as LAST is placed before the last monitor that
 203   registered as LAST, and so on. The first monitor that registers as DEFAULT is
 204   placed before the last monitor, if any, that registered as LAST. The next
 205   monitor that registers as DEFAULT is placed before the last monitor that
 206   registered as DEFAULT, and so on.
 207 * For a detailed description of this call see the chapter "Character Device
 208   Monitors" in the IBM Operating System/2 Version 1.2 I/O Subsystems And
 209   Device Support Volume 1.}
 210 function DosMonReg(MonHandle:word;var InBuf,OutBuf;PosCode,Index:word):word;
 211                                                                          cdecl;
 212
 213 {Move a filtered data record from the monitor's private data area into the
 214 monitor's output buffer.}
 215 {OutBuf - monitor output buffer, DataBuf - monitor's private data area
 216 containing a filtered data record of length ByteCount, this filtered data
 217 record is moved into the monitor's output buffer by this call, ByteCount - size
 218 of the data record.}
 219 {Possible return codes:
 220     0         No_Error
 221     8         Error_Not_Enough_Memory
 222     379       Error_Mon_Invalid_Parms
 223     384       Error_Mon_Data_Too_Large}
 224 {Remarks:
 225 * For a detailed description of the use of this call see the chapter
 226   "Character Device Monitors" in the IBM Operating System/2 Version 1.2 I/O
 227   Subsystems And Device Support Volume 1.}
 228 function DosMonWrite(var OutBuf,DataBuf;ByteCount:word):word; cdecl;
 229
 230
 231 {***************************************************************************}
 232 implementation
 233 {***************************************************************************}
 234
 235
 236 function DosMonClose(MonHandle:word):word; cdecl;
 237 external 'EMXWRAP' index 403;
 238 {external 'MONCALLS' index 3;}
 239
 240 function DosMonOpen(DevName:PChar;var MonHandle:word):word; cdecl;
 241 external 'EMXWRAP' index 404;
 242 {external 'MONCALLS' index 4;}
 243
 244 function DosMonOpen(DevName:string;var MonHandle:word):word;
 245 var
 246   i : byte;
 247 begin
 248     if DevName[0]=#255 then
 249     begin
 250         I:=byte(DevName[0]);
 251         Move(DevName[1],DevName[0],255);
 252         DevName[255]:=#0;
 253         DosMonOpen:=DosMonOpen(@DevName,MonHandle);
 254     end else
 255     begin
 256         DevName[Succ(byte(DevName[0]))]:=#0;
 257         DosMonOpen:=DosMonOpen(@DevName[1],MonHandle);
 258     end;
 259 end;
 260
 261 function DosMonRead(var InBuf;WaitFlag:word;var DataBuf;
 262                                                var ByteCount:word):word; cdecl;
 263 external 'EMXWRAP' index 402;
 264 {external 'MONCALLS' index 2;}
 265
 266 function DosMonReg(MonHandle:word;var InBuf,OutBuf;PosCode,Index:word):word;
 267                                                                          cdecl;
 268 external 'EMXWRAP' index 405;
 269 {external 'MONCALLS' index 5;}
 270
 271 function DosMonWrite(var OutBuf,DataBuf;ByteCount:word):word; cdecl;
 272 external 'EMXWRAP' index 401;
 273 {external 'MONCALLS' index 1;}
 274
 275
 276 end.
 277
 278 {
 279   $Log$
 280   Revision 1.1  2002/02/19 08:25:55  sasu
 281   Initial revision
 282
 283   Revision 1.1  2000/07/13 06:31:06  michael
 284   + Initial import
 285
 286   Revision 1.5  2000/01/09 21:01:59  hajny
 287     * cdecl added
 288
 289 }