Windows structure
signature WINDOWS (* OPTIONAL *)
structure Windows :> WINDOWS (* OPTIONAL *)
The Windows structure provides a high-level interface to various system features based on the Microsoft Microsoft Windows operating system model. These functions include the ability to create and communicate with separate processes, as well as to interact with the registry and file subsystems. In particular, using this module, a program can invoke a separate process and obtain input and output streams connected to the standard output and input streams, respectively, of the other process. The functions provide a richer and more detailed interface than the comparable functions provided by the substructures in OS.
structure Key : sig
include BIT_FLAGS
val allAccess : flags
val createLink : flags
val createSubKey : flags
val enumerateSubKeys : flags
val execute : flags
val notify : flags
val queryValue : flags
val read : flags
val setValue : flags
val write : flags
end
structure Reg : sig
eqtype hkey
val classesRoot : hkey
val currentUser : hkey
val localMachine : hkey
val users : hkey
val performanceData : hkey
val currentConfig : hkey
val dynData : hkey
datatype create_result
= CREATED_NEW_KEY of hkey
| OPENED_EXISTING_KEY of hkey
val createKeyEx : hkey * string * Key.flags
-> create_result
val openKeyEx : hkey * string * Key.flags -> hkey
val closeKey : hkey -> unit
val deleteKey : hkey * string -> unit
val deleteValue : hkey * string -> unit
val enumKeyEx : hkey * int -> string option
val enumValueEx : hkey * int -> string option
datatype value
= SZ of string
| DWORD of SysWord.word
| BINARY of Word8Vector.vector
| MULTI_SZ of string list
| EXPAND_SZ of string
val queryValueEx : hkey * string -> value option
val setValueEx : hkey * string * value -> unit
end
structure Config : sig
val platformWin32s : SysWord.word
val platformWin32Windows : SysWord.word
val platformWin32NT : SysWord.word
val platformWin32CE : SysWord.word
val getVersionEx : unit
-> {
majorVersion : SysWord.word,
minorVersion : SysWord.word,
buildNumber : SysWord.word,
platformId : SysWord.word,
csdVersion : string
}
val getWindowsDirectory : unit -> string
val getSystemDirectory : unit -> string
val getComputerName : unit -> string
val getUserName : unit -> string
end
structure DDE : sig
type info
val startDialog : string * string -> info
val executeString : info * string * int * Time.time
-> unit
val stopDialog : info -> unit
end
val getVolumeInformation : string
-> {
volumeName : string,
systemName : string,
serialNumber : SysWord.word,
maximumComponentLength : int
}
val findExecutable : string -> string option
val launchApplication : string * string -> unit
val openDocument : string -> unit
val simpleExecute : string * string -> OS.Process.status
type ('a,'b) proc
val execute : string * string -> ('a, 'b) proc
val textInstreamOf : (TextIO.instream, 'a) proc
-> TextIO.instream
val binInstreamOf : (BinIO.instream, 'a) proc
-> BinIO.instream
val textOutstreamOf : ('a, TextIO.outstream) proc
-> TextIO.outstream
val binOutstreamOf : ('a, BinIO.outstream) proc
-> BinIO.outstream
val reap : ('a, 'b) proc -> OS.Process.status
structure Status : sig
type status = SysWord.word
val accessViolation : status
val arrayBoundsExceeded : status
val breakpoint : status
val controlCExit : status
val datatypeMisalignment : status
val floatDenormalOperand : status
val floatDivideByZero : status
val floatInexactResult : status
val floatInvalidOperation : status
val floatOverflow : status
val floatStackCheck : status
val floatUnderflow : status
val guardPageViolation : status
val integerDivideByZero : status
val integerOverflow : status
val illegalInstruction : status
val invalidDisposition : status
val invalidHandle : status
val inPageError : status
val noncontinuableException : status
val pending : status
val privilegedInstruction : status
val singleStep : status
val stackOverflow : status
val timeout : status
val userAPC : status
end
val fromStatus : OS.Process.status -> Status.status
val exit : Status.status -> 'a
structure Key
Key substructure contains flags for specifying security settings when opening and creating keys in the registry.
val allAccess : flags
queryValue, enumerateSubKeys, notify, createSubKey, createLink, and setValue flags.
val createLink : flags
val createSubKey : flags
val enumerateSubKeys : flags
val execute : flags
val notify : flags
val queryValue : flags
val read : flags
queryValue, enumerateSubKeys, and notify flags.
val setValue : flags
val write : flags
setValue and createSubKey flags.
structure Reg
eqtype hkey
val classesRoot : hkey
val currentUser : hkey
val localMachine : hkey
val users : hkey
val performanceData : hkey
val currentConfig : hkey
val dynData : hkey
createKeyEx (hkey, skey, regsam)
Implementation note:
This passes
REG_OPTION_NON_VOLATILEoption,NULLClass, andSECURITY_ATTRIBUTEarguments to the Win32 call.
openKeyEx (hkey, skey, regsam)
closeKey hkey
deleteKey (hkey, skey)
deleteValue (hkey, valname)
enumKeyEx (hkey, ind)
SOME of a string for each defined subkey. To enumerate all the subkeys, start with the index at zero and increment it until the function returns NONE. The function raises the Subscript exception if ind is invalid.
enumValueEx (hkey, ind)
SOME of a string for each defined value. To enumerate all the values, start with the index at zero and increment it until the function returns NONE. The function raises the Subscript exception if ind is invalid.
datatype value
= SZ of string
| DWORD of SysWord.word
| BINARY of Word8Vector.vector
| MULTI_SZ of string list
| EXPAND_SZ of string
SZ corresponds to strings, DWORD to 32-bit numbers, BINARY to arbitrary binary values, MULTI_SZ to lists of strings, and EXPAND_SZ to strings containing environment variables.
queryValueEx (hkey, name)
value datatype is returned as a BINARY value. If the value does not exist in the key, the function returns NONE. Any other error, such as having insufficient access rights to the registry key, results in the OS.SysErr exception being raised.
A common use of a registry value is to override the default behavior of a program. The normal case is when the registry value is unset. Using an option type allows for the result of queryValueEx to indicate the presence or absence of the key.
setValueEx (hkey, name, v)
structure Config
val platformWin32s : SysWord.word
val platformWin32Windows : SysWord.word
val platformWin32NT : SysWord.word
val platformWin32CE : SysWord.word
val getVersionEx : unit
-> {
majorVersion : SysWord.word,
minorVersion : SysWord.word,
buildNumber : SysWord.word,
platformId : SysWord.word,
csdVersion : string
}
platformWin32s, platformWin32Windows, platformWin32NT, and platformWin32CE to determine the type of platform. Note that additional values for other platforms may be returned.
The major and minor version numbers allow additional distinctions. In the case where platformId is platformWin32Windows, we have:
minorVersion
| System |
|---|---|
| 0 | Windows 95 |
| > 0 | Windows 98 |
In the case where platformId is platformWin32NT, we have:
majorVersion
|
minorVersion
| System |
|---|---|---|
| 4 | 0 | Windows NT |
| 5 | 0 | Windows 2000 |
| 5 | > 0 | Windows XP |
val getWindowsDirectory : unit -> string
"C:\Windows" on Windows 95 or "C:\Winnt" on Windows NT.
val getSystemDirectory : unit -> string
"C:\Windows\System" or "C:\Winnt\System32".
val getComputerName : unit -> string
val getUserName : unit -> string
structure DDE
startDialog (service, topic)
info value created by these operations.
executeString (info, cmd, retry, delay)
stopDialog info
getVolumeInformation root
volumeName field contains the name of the volume; the systemName field contains its type (e.g., "FAT" or "NTFS"); the serialNumber field contains the serial number; and the maximumComponentLength field specifies the maximum length of any component of a pathname on this system.
findExecutable name
NONE if no such file exists.
launchApplication (file, arg)
OS.SysErr if file is not executable or if it cannot be run.
Implementation note:
This should be implemented using
ShellExecute, passingSW_SHOWNORMALto the underlying API call.
openDocument file
Implementation note:
This should pass
SW_SHOWNORMALto the underlyingShellExecuteAPI call.
simpleExecute (cmd, arg)
OS.Process.system but it can be used in cases where the latter does not work, and its return value provides more information about the exit status of the child process.
Implementation note:
This corresponds to the use of
CreateProcess.
type ('a,'b) proc
execute. The type parameters are witness types for the types of streams that can be returned.
execute (cmd, arg)
Implementation note:
This also corresponds to the use of
CreateProcess. Redirection of the standard streams can be handled using thehStdInputandhStdOutputfields in theSTARTUPINFOparameter.
textInstreamOf pr
binInstreamOf pr
instream connected to the standard output stream of the process pr.
Note that multiple calls to these functions on the same proc value will result in multiple streams that all share the same underlying open file descriptor, which can lead to unpredictable effects because
textOutstreamOf pr
binOutstreamOf pr
outstream connected to the standard input stream of the process pr.
Note that multiple calls to these functions on the same proc value will result in multiple streams that all share the same underlying open file descriptor, which can lead to unpredictable effects due to buffering.
reap pr
reap is applied again to pr, it should immediately return the previous exit status.
Implementation note:
Typically, one cannot rely on the underlying operating system to provide the exit status of a terminated process after it has done so once. Thus, the exit status probably needs to be cached. Also note that
reapshould not return until the process being monitored has terminated. In particular, implementations should be careful not to return if the process has only been suspended.
structure Status
Status substructure defines the possible system-specific interpretations of OS.Process.status values.
fromStatus s
exit st
OS.Process.atExit, flushes and closes all I/O streams, then terminates the SML process with termination status st.
BIT_FLAGS,OS.FileSys,OS.Process,TextIO,Time
This structure provides a minimal view of the system calls available across Microsoft operating systems. It focuses on managing the registry, and executing programs. The function Windows.findExecutable and the facilities in the Config substructure allow the programmer to determine if and where a program can be found on a given machine.
Future extensions of the Basis Library might give access to more features, either by including additional substructures or as a separate top-level module.
Rationale:
As usual, platform identification and exit status values are not handled by datatypes to allow for future extensions.
Generated April 12, 2004
Last Modified July 1, 2002
Comments to John Reppy.
This document may be distributed freely over the internet as long as the copyright notice and license terms below are prominently displayed within every machine-readable copy.
|
Copyright © 2004 AT&T and Lucent Technologies. All rights reserved.
Permission is granted for internet users to make one paper copy for their
own personal use. Further hardcopy reproduction is strictly prohibited.
Permission to distribute the HTML document electronically on any medium
other than the internet must be requested from the copyright holders by
contacting the editors.
Printed versions of the SML Basis Manual are available from Cambridge
University Press.
To order, please visit
www.cup.org (North America) or
www.cup.cam.ac.uk (outside North America). |