Class: Win32::Process

Inherits:
Object
  • Object
show all
Includes:
APIMapper
Defined in:
lib/Win32/Process.rb

Overview

This class creates a Windows process and can manipulate it.

Constant Summary collapse

WAIT_INFINITE =

constsFor: “Wait Return Codes” (from WinUser.h)

0xFFFFFFFF
WAIT_FAILED = 
0xFFFFFFFF
WAIT_OBJECT_0 = 
0x00000000
WAIT_ABANDONED = 
0x00000080
WAIT_IO_COMPLETION = 
0x000000C0
WAIT_TIMEOUT = 
0x00000102
DEBUG_PROCESS =

constsFor: “Process Creation Flags” (from WinBase.h)

0x00000001
DEBUG_ONLY_THIS_PROCESS = 
0x00000002
CREATE_SUSPENDED = 
0x00000004
DETACHED_PROCESS = 
0x00000008
CREATE_NEW_CONSOLE = 
0x00000010
NORMAL_PRIORITY_CLASS = 
0x00000020
IDLE_PRIORITY_CLASS = 
0x00000040
HIGH_PRIORITY_CLASS = 
0x00000080
REALTIME_PRIORITY_CLASS = 
0x00000100
CREATE_NEW_PROCESS_GROUP = 
0x00000200
CREATE_UNICODE_ENVIRONMENT = 
0x00000400
CREATE_SEPARATE_WOW_VDM = 
0x00000800
CREATE_SHARED_WOW_VDM = 
0x00001000
CREATE_FORCED_DOS = 
0x00002000
CREATE_DEFAULT_ERROR_MODE = 
0x04000000
CREATE_NO_WINDOW = 
0x08000000
PROFILE_USER = 
0x10000000
PROFILE_KERNEL = 
0x20000000
PROFILE_SERVER = 
0x40000000
THREAD_BASE_PRIORITY_LOWRT =

constsFor: “Thread Creation Flags” (from WinBase.h, WinNT.h)

15
THREAD_BASE_PRIORITY_MAX = 
2
THREAD_BASE_PRIORITY_MIN = 
-2
THREAD_BASE_PRIORITY_IDLE = 
-15
MAXLONG = 
0x7FFFFFFFFFFFFFFF
THREAD_PRIORITY_LOWEST = 
THREAD_BASE_PRIORITY_MIN
THREAD_PRIORITY_BELOW_NORMAL = 
THREAD_PRIORITY_LOWEST + 1
THREAD_PRIORITY_NORMAL = 
0
THREAD_PRIORITY_HIGHEST = 
THREAD_BASE_PRIORITY_MAX
THREAD_PRIORITY_ABOVE_NORMAL = 
THREAD_PRIORITY_HIGHEST - 1
THREAD_PRIORITY_ERROR_RETURN = 
MAXLONG
THREAD_PRIORITY_TIME_CRITICAL = 
THREAD_BASE_PRIORITY_LOWRT
THREAD_PRIORITY_IDLE = 
THREAD_BASE_PRIORITY_IDLE

Constants included from APIMapper

APIMapper::DLL, APIMapper::HANDLE, APIMapper::IN, APIMapper::NAME, APIMapper::OUT

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from APIMapper

Initialize, #WCall, WCall

Constructor Details

#initialize ⇒ Process

class methodsFor: “initialization”



342
343
344
 
# File 'lib/Win32/Process.rb', line 342

def initialize()
	@proc = nil
end

Instance Attribute Details

#proc ⇒ Object (readonly)

Returns the value of attribute proc.



339
340
341
 
# File 'lib/Win32/Process.rb', line 339

def proc
  @proc
end

Class Method Details

.create(p_strAppName, p_strCmdLine, p_processAttrs = nil, p_threadAttrs = nil, p_bInheritHandles = false, p_nCreationFlags = NORMAL_PRIORITY_CLASS, p_strEnvironment = nil, p_strCurrentDirectory = nil, p_startupInfo = nil) ⇒ Object

methodsFor: “process creation”



348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
 
# File 'lib/Win32/Process.rb', line 348

def Process.create(
		p_strAppName,
		p_strCmdLine,
		p_processAttrs        = nil,
		p_threadAttrs         = nil,
		p_bInheritHandles     = false,
		p_nCreationFlags      = NORMAL_PRIORITY_CLASS,
		p_strEnvironment      = nil,
		p_strCurrentDirectory = nil,
		p_startupInfo         = nil)
	process = Process.new()
	process.create(
		p_strAppName, p_strCmdLine,
		p_processAttrs, p_threadAttrs, p_bInheritHandles,
		p_nCreationFlags, p_strEnvironment, p_strCurrentDirectory, p_startupInfo)
	return process			
end

.open(p_processAttrs, p_bInheritHandles, p_pid) ⇒ Object 



394
395
396
397
 
# File 'lib/Win32/Process.rb', line 394

def Process.open(p_processAttrs, p_bInheritHandles, p_pid)
	process = Process.new()
	process.open(p_processAttrs, p_bInheritHandles, p_pid)
end

Instance Method Details

#close ⇒ Object

methodsFor: “closing”



408
409
410
 
# File 'lib/Win32/Process.rb', line 408

def close
	return 0 if @proc.nil?
end

#close_handles ⇒ Object 



436
437
438
439
440
441
442
 
# File 'lib/Win32/Process.rb', line 436

def close_handles
	if !@proc.nil? then
		closeHandle = Win32API.new("kernel32", "CloseHandle", ['L'], 'L')
		closeHandle.Call(@proc.hProcess) if @proc.hProcess != nil
		closeHandle.Call(@proc.hThread) if @proc.hThread != nil
	end
end

#create(p_strAppName, p_strCmdLine, p_processAttrs = nil, p_threadAttrs = nil, p_bInheritHandles = false, p_nCreationFlags = NORMAL_PRIORITY_CLASS, p_strEnvironment = nil, p_strCurrentDirectory = nil, p_startupInfo = nil) ⇒ Object 



366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
 
# File 'lib/Win32/Process.rb', line 366

def create(
		p_strAppName,
		p_strCmdLine,
		p_processAttrs        = nil,
		p_threadAttrs         = nil,
		p_bInheritHandles     = false,
		p_nCreationFlags      = NORMAL_PRIORITY_CLASS,
		p_strEnvironment      = nil,
		p_strCurrentDirectory = nil,
		p_startupInfo         = nil)
	self.close() if !@proc.nil?
	pProcessInfo = " " * ProcessInfo.sizeof
	ret = WCall('CreateProcess',
				p_strAppName, p_strCmdLine,
				p_processAttrs, p_threadAttrs, p_bInheritHandles ? 1 : 0,
				p_nCreationFlags, p_strEnvironment, p_strCurrentDirectory,
				p_startupInfo.nil? ? StartupInfo.new().pack : p_startupInfo.pack,
				pProcessInfo)
	$TRACE.debug 9, "after CreateProcess ret = #{ret.inspect}"
	@proc = ProcessInfo.unpack(pProcessInfo)
	
	if ret == 0 then
		raise Win32::Error.new("process '#{p_strAppName}' could not be created because, ")
	elsif @proc.pid == 0
		raise Win32::Error.new, "process '#{p_strAppName}' could not be created (unknown reason)", caller
	end
end

#hProcess ⇒ Object

methodsFor: “accessing”



446
447
448
 
# File 'lib/Win32/Process.rb', line 446

def hProcess
	return  @proc.nil? ? nil : @proc.hProcess
end

#hThread ⇒ Object 



450
451
452
 
# File 'lib/Win32/Process.rb', line 450

def hThread
	return  @proc.nil? ? nil : @proc.hThread
end

#open(p_processAttrs, p_bInheritHandles, p_pid) ⇒ Object

Raises:



399
400
401
402
403
404
 
# File 'lib/Win32/Process.rb', line 399

def open(p_processAttrs, p_bInheritHandles, p_pid)
	self.close() if !@proc.nil?
	ret = WCall('CreateProcess', p_processAttrs, p_bInheritHandles, p_pid)
	raise Win32::Error.new, "Cannot Open Process", caller if 0 == ret
	@proc = ProcessInfo.new(ret)
end

#pid ⇒ Object 



454
455
456
 
# File 'lib/Win32/Process.rb', line 454

def pid
	return  @proc.nil? ? nil : @proc.pid
end

#terminate(p_nExitCode) ⇒ Object

methodsFor: “terminating”

Raises:



414
415
416
417
418
 
# File 'lib/Win32/Process.rb', line 414

def terminate(p_nExitCode)
	raise Win32::Error.new, "Missing Process Info", caller if @proc.nil?
	ret = WCall('TerminateProcess', @proc.hProcess, p_nExitCode)
	raise Win32::Error.new, "Error terminating process #{@proc.hProcess}", caller if 0 == ret
end

#tid ⇒ Object 



458
459
460
 
# File 'lib/Win32/Process.rb', line 458

def tid
	return  @proc.nil? ? nil : @proc.tid
end

#to_s ⇒ Object

methodsFor: “printing”



464
465
466
 
# File 'lib/Win32/Process.rb', line 464

def to_s
	return @proc.nil? ? "nil" : @proc.to_s
end

#wait(p_nMilliseconds, p_bAlertable = true) ⇒ Object

methodsFor: “signalling”

Raises:



422
423
424
425
426
427
 
# File 'lib/Win32/Process.rb', line 422

def wait(p_nMilliseconds, p_bAlertable = true)
	raise Win32::Error.new, "Missing Process Info", caller if @proc.nil?
	ret = WCall('WaitForObject', @proc.hProcess, p_nMilliseconds, p_bAlertable ? 1 : 0)
	raise Win32::Error.new, "Error while waiting for #{@proc.pid}", caller if ret == WAIT_FAILED
	return ret
end

#waitForInputIdle(p_nMilliseconds) ⇒ Object

Raises:



429
430
431
432
433
434
 
# File 'lib/Win32/Process.rb', line 429

def waitForInputIdle(p_nMilliseconds)
	raise Win32::Error.new, "Missing Process Info", caller if @proc.nil?
	ret = WCall('WaitForInputIdle', @proc.hProcess, p_nMilliseconds)
	raise Win32::Error.new, "Error while waiting for #{@proc.pid}", caller if ret == WAIT_FAILED
	return ret
end