1 /* Copyright (c) 2010 Daniel Doubrovkine, All Rights Reserved 2 * 3 * The contents of this file is dual-licensed under 2 4 * alternative Open Source/Free licenses: LGPL 2.1 or later and 5 * Apache License 2.0. (starting with JNA version 4.0.0). 6 * 7 * You can freely decide which license you want to apply to 8 * the project. 9 * 10 * You may obtain a copy of the LGPL License at: 11 * 12 * http://www.gnu.org/licenses/licenses.html 13 * 14 * A copy is also included in the downloadable source code package 15 * containing JNA, in file "LGPL2.1". 16 * 17 * You may obtain a copy of the Apache License at: 18 * 19 * http://www.apache.org/licenses/ 20 * 21 * A copy is also included in the downloadable source code package 22 * containing JNA, in file "AL2.0". 23 */ 24 package com.sun.jna.platform.win32; 25 26 import com.sun.jna.Native; 27 import com.sun.jna.Pointer; 28 import com.sun.jna.Structure; 29 import com.sun.jna.platform.win32.WinBase.FE_EXPORT_FUNC; 30 import com.sun.jna.platform.win32.WinBase.FE_IMPORT_FUNC; 31 import com.sun.jna.platform.win32.WinBase.PROCESS_INFORMATION; 32 import com.sun.jna.platform.win32.WinBase.SECURITY_ATTRIBUTES; 33 import com.sun.jna.platform.win32.WinBase.STARTUPINFO; 34 import com.sun.jna.platform.win32.WinDef.BOOLByReference; 35 import com.sun.jna.platform.win32.WinDef.DWORD; 36 import com.sun.jna.platform.win32.WinDef.DWORDByReference; 37 import com.sun.jna.platform.win32.WinDef.ULONG; 38 import com.sun.jna.platform.win32.WinNT.ACL; 39 import com.sun.jna.platform.win32.WinNT.GENERIC_MAPPING; 40 import com.sun.jna.platform.win32.WinNT.HANDLE; 41 import com.sun.jna.platform.win32.WinNT.HANDLEByReference; 42 import com.sun.jna.platform.win32.WinNT.PACLByReference; 43 import com.sun.jna.platform.win32.WinNT.PRIVILEGE_SET; 44 import com.sun.jna.platform.win32.WinNT.PSID; 45 import com.sun.jna.platform.win32.WinNT.PSIDByReference; 46 import com.sun.jna.platform.win32.WinNT.SECURITY_DESCRIPTOR; 47 import com.sun.jna.platform.win32.WinNT.SECURITY_DESCRIPTOR_RELATIVE; 48 import com.sun.jna.platform.win32.WinReg.HKEY; 49 import com.sun.jna.platform.win32.WinReg.HKEYByReference; 50 import com.sun.jna.platform.win32.Winsvc.ChangeServiceConfig2Info; 51 import com.sun.jna.platform.win32.Winsvc.HandlerEx; 52 import com.sun.jna.platform.win32.Winsvc.SC_HANDLE; 53 import com.sun.jna.platform.win32.Winsvc.SERVICE_STATUS; 54 import com.sun.jna.platform.win32.Winsvc.SERVICE_STATUS_HANDLE; 55 import com.sun.jna.platform.win32.Winsvc.SERVICE_STATUS_PROCESS; 56 import com.sun.jna.platform.win32.Winsvc.SERVICE_TABLE_ENTRY; 57 import com.sun.jna.ptr.IntByReference; 58 import com.sun.jna.ptr.LongByReference; 59 import com.sun.jna.ptr.PointerByReference; 60 import com.sun.jna.ptr.ShortByReference; 61 import com.sun.jna.win32.StdCallLibrary; 62 import com.sun.jna.win32.W32APIOptions; 63 64 /** 65 * Advapi32.dll Interface. 66 * 67 * @author dblock[at]dblock.org 68 */ 69 public interface Advapi32 extends StdCallLibrary { 70 Advapi32 INSTANCE = Native.load("Advapi32", Advapi32.class, W32APIOptions.DEFAULT_OPTIONS); 71 72 int MAX_KEY_LENGTH = 255; 73 int MAX_VALUE_NAME = 16383; 74 75 int RRF_RT_ANY = 0x0000ffff; 76 int RRF_RT_DWORD = 0x00000018; 77 int RRF_RT_QWORD = 0x00000048; 78 int RRF_RT_REG_BINARY = 0x00000008; 79 int RRF_RT_REG_DWORD = 0x00000010; 80 int RRF_RT_REG_EXPAND_SZ = 0x00000004; 81 int RRF_RT_REG_MULTI_SZ = 0x00000020; 82 int RRF_RT_REG_NONE = 0x00000001; 83 int RRF_RT_REG_QWORD = 0x00000040; 84 int RRF_RT_REG_SZ = 0x00000002; 85 86 /** 87 * LOGON_WITH_PROFILE: 0x00000001<br> 88 * Log on, then load the user profile in the HKEY_USERS registry key.<br> 89 * The function returns after the profile is loaded. <br> 90 * Loading the profile can be time-consuming, so it is best to use this 91 * value only if you must access the information in the HKEY_CURRENT_USER 92 * registry key.<br> 93 * Windows Server 2003: The profile is unloaded after the new process is 94 * terminated, whether or not it has created child processes.<br> 95 * Windows XP: The profile is unloaded after the new process and all child 96 * processes it has created are terminated.<br> 97 */ 98 int LOGON_WITH_PROFILE = 0x00000001; 99 100 /** 101 * LOGON_NETCREDENTIALS_ONLY: 0x00000002<br> 102 * Log on, but use the specified credentials on the network only.<br> 103 * The new process uses the same token as the caller, but the system creates 104 * a new logon session within LSA, and the process uses the specified 105 * credentials as the default credentials. <br> 106 * This value can be used to create a process that uses a different set of 107 * credentials locally than it does remotely.<br> 108 * This is useful in inter-domain scenarios where there is no trust 109 * relationship.<br> 110 * The system does not validate the specified credentials.<br> 111 * Therefore, the process can start, but it may not have access to network 112 * resources. 113 */ 114 int LOGON_NETCREDENTIALS_ONLY = 0x00000002; 115 116 /** 117 * Retrieves the name of the user associated with the current thread. 118 * http://msdn.microsoft.com/en-us/library/ms724432(VS.85).aspx 119 * 120 * @param buffer 121 * Buffer to receive the user's logon name. 122 * @param len 123 * On input, the size of the buffer, on output the number of 124 * characters copied into the buffer, including the terminating 125 * null character. 126 * @return True if succeeded. 127 */ GetUserNameW(char[] buffer, IntByReference len)128 boolean GetUserNameW(char[] buffer, IntByReference len); 129 130 /** 131 * Accepts the name of a system and anaccount as input and retrieves a 132 * security identifier (SID) for the account and the name of the domain on 133 * which the account was found. 134 * http://msdn.microsoft.com/en-us/library/aa379159(VS.85).aspx 135 * 136 * @param lpSystemName 137 * Specifies the name of the system. 138 * @param lpAccountName 139 * Specifies the account name. 140 * @param Sid 141 * Receives the SID structure that corresponds to the account 142 * name pointed to by the lpAccountName parameter. 143 * @param cbSid 144 * On input, this value specifies the size, in bytes, of the Sid 145 * buffer. If the function fails because the buffer is too small 146 * or if cbSid is zero, this variable receives the required 147 * buffer size. 148 * @param ReferencedDomainName 149 * Receives the name of the domain where the account name is 150 * found. 151 * @param cchReferencedDomainName 152 * On input, this value specifies the size, in TCHARs, of the 153 * ReferencedDomainName buffer. If the function fails because the 154 * buffer is too small, this variable receives the required 155 * buffer size, including the terminating null character. 156 * @param peUse 157 * SID_NAME_USE enumerated type that indicates the type of the 158 * account when the function returns. 159 * @return True if the function was successful, False otherwise. 160 */ LookupAccountName(String lpSystemName, String lpAccountName, PSID Sid, IntByReference cbSid, char[] ReferencedDomainName, IntByReference cchReferencedDomainName, PointerByReference peUse)161 boolean LookupAccountName(String lpSystemName, String lpAccountName, 162 PSID Sid, IntByReference cbSid, char[] ReferencedDomainName, 163 IntByReference cchReferencedDomainName, PointerByReference peUse); 164 165 /** 166 * Retrieves the name of the account for this SID and the name of the first 167 * domain on which this SID is found. 168 * 169 * @param lpSystemName 170 * Specifies the target computer. 171 * @param Sid 172 * The SID to look up. 173 * @param lpName 174 * Buffer that receives a null-terminated string that contains 175 * the account name that corresponds to the lpSid parameter. 176 * @param cchName 177 * On input, specifies the size, in TCHARs, of the lpName buffer. 178 * If the function fails because the buffer is too small or if 179 * cchName is zero, cchName receives the required buffer size, 180 * including the terminating null character. 181 * @param ReferencedDomainName 182 * Pointer to a buffer that receives a null-terminated string 183 * that contains the name of the domain where the account name 184 * was found. 185 * @param cchReferencedDomainName 186 * On input, specifies the size, in TCHARs, of the 187 * lpReferencedDomainName buffer. If the function fails because 188 * the buffer is too small or if cchReferencedDomainName is zero, 189 * cchReferencedDomainName receives the required buffer size, 190 * including the terminating null character. 191 * @param peUse 192 * Pointer to a variable that receives a SID_NAME_USE value that 193 * indicates the type of the account. 194 * @return If the function succeeds, the function returns nonzero. If the 195 * function fails, it returns zero. To get extended error 196 * information, call GetLastError. 197 */ LookupAccountSid(String lpSystemName, PSID Sid, char[] lpName, IntByReference cchName, char[] ReferencedDomainName, IntByReference cchReferencedDomainName, PointerByReference peUse)198 boolean LookupAccountSid(String lpSystemName, PSID Sid, 199 char[] lpName, IntByReference cchName, char[] ReferencedDomainName, 200 IntByReference cchReferencedDomainName, PointerByReference peUse); 201 202 /** 203 * Convert a security identifier (SID) to a string format suitable for 204 * display, storage, or transmission. 205 * 206 * @param Sid 207 * The SID structure to be converted. 208 * @param StringSid 209 * Pointer to a variable that receives a pointer to a 210 * null-terminated SID string. To free the returned buffer, call 211 * the LocalFree function. 212 * @return {@code true} if the function was successful - call {@code GetLastError()} 213 * to check failure reason 214 * @see <A HREF="http://msdn.microsoft.com/en-us/library/aa376399(VS.85).aspx">ConvertSidToStringSid</A> 215 */ ConvertSidToStringSid(PSID Sid, PointerByReference StringSid)216 boolean ConvertSidToStringSid(PSID Sid, PointerByReference StringSid); 217 218 /** 219 * Convert a string-format security identifier (SID) into a valid, 220 * functional SID. 221 * 222 * 223 * @param StringSid 224 * The string-format SID to convert. 225 * @param Sid 226 * Receives a pointer to the converted SID. To free the returned buffer, call 227 * the LocalFree function. 228 * @return {@code true} if the function was successful - call {@code GetLastError()} 229 * to check failure reason 230 * @see <A HREF="http://msdn.microsoft.com/en-us/library/aa376402(VS.85).aspx">ConvertStringSidToSid</A> 231 */ ConvertStringSidToSid(String StringSid, PSIDByReference Sid)232 boolean ConvertStringSidToSid(String StringSid, PSIDByReference Sid); 233 234 /** 235 * Returns the length, in bytes, of a valid security identifier (SID). 236 * http://msdn.microsoft.com/en-us/library/aa446642(VS.85).aspx 237 * 238 * @param pSid 239 * A pointer to the SID structure whose length is returned. 240 * @return Length of the SID. 241 */ GetLengthSid(PSID pSid)242 int GetLengthSid(PSID pSid); 243 244 /** 245 * The IsValidSid function validates a security identifier (SID) by 246 * verifying that the revision number is within a known range, and that the 247 * number of subauthorities is less than the maximum. 248 * 249 * @param pSid 250 * Pointer to the SID structure to validate. This parameter 251 * cannot be NULL. 252 * @return If the SID structure is valid, the return value is nonzero. If 253 * the SID structure is not valid, the return value is zero. There 254 * is no extended error information for this function; do not call 255 * GetLastError. 256 */ IsValidSid(PSID pSid)257 boolean IsValidSid(PSID pSid); 258 259 /** 260 * he EqualSid function tests two security identifier (SID) values for equality. 261 * Two SIDs must match exactly to be considered equal. 262 * @param pSid1 263 * A pointer to the first SID structure to compare. This structure is assumed to be valid. 264 * @param pSid2 265 * A pointer to the second SID structure to compare. This structure is assumed to be valid. 266 * @return If the SID structures are equal, the return value is nonzero. 267 * If the SID structures are not equal, the return value is zero. To get extended error 268 * information, call GetLastError. 269 * If either SID structure is not valid, the return value is undefined. 270 */ EqualSid(PSID pSid1, PSID pSid2)271 boolean EqualSid(PSID pSid1, PSID pSid2); 272 273 /** 274 * Compares a SID to a well known SID and returns TRUE if they match. 275 * 276 * @param pSid 277 * SID to test. 278 * @param wellKnownSidType 279 * Member of the WELL_KNOWN_SID_TYPE enumeration to compare with 280 * the SID at pSid. 281 * @return True if the SID is of a given well known type, false otherwise. 282 */ IsWellKnownSid(PSID pSid, int wellKnownSidType)283 boolean IsWellKnownSid(PSID pSid, int wellKnownSidType); 284 285 /** 286 * The CreateWellKnownSid function creates a SID for predefined aliases. 287 * 288 * @param wellKnownSidType 289 * Member of the WELL_KNOWN_SID_TYPE enumeration that specifies 290 * what the SID will identify. 291 * @param domainSid 292 * Pointer to a SID that identifies the domain control to use 293 * when creating the SID. Pass NULL to use the local computer. 294 * @param pSid 295 * Pointer to memory where CreateWellKnownSid will store the new 296 * SID. 297 * @param cbSid 298 * Pointer to a DWORD that contains the number of bytes available 299 * at pSid. The CreateWellKnownSid function stores the number of 300 * bytes actually used at this location. 301 * @return If the function succeeds, the return value is nonzero. If the 302 * function fails, the return value is zero. For extended error 303 * information, call GetLastError. 304 */ CreateWellKnownSid(int wellKnownSidType, PSID domainSid, PSID pSid, IntByReference cbSid)305 boolean CreateWellKnownSid(int wellKnownSidType, PSID domainSid, 306 PSID pSid, IntByReference cbSid); 307 308 /** 309 * The InitializeSecurityDescriptor function initializes a new security descriptor. 310 * @param pSecurityDescriptor 311 * A pointer to a SECURITY_DESCRIPTOR structure that the function initializes. 312 * @param dwRevision 313 * The revision level to assign to the security descriptor. This parameter 314 * must be SECURITY_DESCRIPTOR_REVISION. 315 * @return If the function succeeds, the return value is nonzero. If the 316 * function fails, the return value is zero. For extended error 317 * information, call GetLastError. 318 */ InitializeSecurityDescriptor(SECURITY_DESCRIPTOR pSecurityDescriptor, int dwRevision)319 boolean InitializeSecurityDescriptor(SECURITY_DESCRIPTOR pSecurityDescriptor, int dwRevision); 320 321 /** 322 * The GetSecurityDescriptorControl function retrieves a security descriptor control and revision information. 323 * @param pSecurityDescriptor 324 * A pointer to a SECURITY_DESCRIPTOR structure whose control and revision 325 * information the function retrieves. 326 * @param pControl 327 * A pointer to a SECURITY_DESCRIPTOR_CONTROL structure that receives the security descriptor's 328 * control information. 329 * @param lpdwRevision 330 * A pointer to a variable that receives the security descriptor's revision value. 331 * This value is always set, even when GetSecurityDescriptorControl returns an error. 332 * @return If the function succeeds, the return value is nonzero. If the 333 * function fails, the return value is zero. For extended error 334 * information, call GetLastError. 335 */ GetSecurityDescriptorControl(SECURITY_DESCRIPTOR pSecurityDescriptor, ShortByReference pControl, IntByReference lpdwRevision)336 boolean GetSecurityDescriptorControl(SECURITY_DESCRIPTOR pSecurityDescriptor, ShortByReference pControl, IntByReference lpdwRevision); 337 338 /** 339 * The SetSecurityDescriptorControl function sets the control bits of a security descriptor. The function can set only the control 340 * bits that relate to automatic inheritance of ACEs. To set the other control bits of a security descriptor, use the functions, 341 * such as SetSecurityDescriptorDacl, for modifying the components of a security descriptor. 342 * @param pSecurityDescriptor 343 * A pointer to a SECURITY_DESCRIPTOR structure whose control and revision information are set. 344 * @param ControlBitsOfInterest 345 * A SECURITY_DESCRIPTOR_CONTROL mask that indicates the control bits to set. 346 * @param ControlBitsToSet 347 * SECURITY_DESCRIPTOR_CONTROL mask that indicates the new values for the control bits specified by the ControlBitsOfInterest mask. 348 * @return If the function succeeds, the return value is nonzero. If the 349 * function fails, the return value is zero. For extended error 350 * information, call GetLastError. 351 */ SetSecurityDescriptorControl(SECURITY_DESCRIPTOR pSecurityDescriptor, short ControlBitsOfInterest, short ControlBitsToSet)352 boolean SetSecurityDescriptorControl(SECURITY_DESCRIPTOR pSecurityDescriptor, short ControlBitsOfInterest, short ControlBitsToSet); 353 354 /** 355 * The GetSecurityDescriptorOwner function retrieves the owner information from a security descriptor. 356 * @param pSecurityDescriptor 357 * A pointer to a SECURITY_DESCRIPTOR structure whose owner information the function retrieves. 358 * @param pOwner 359 * A pointer to a pointer to a security identifier (SID) that identifies the owner when the function returns. 360 * If the security descriptor does not contain an owner, the function sets the pointer pointed to by pOwner 361 * to NULL and ignores the remaining output parameter, lpbOwnerDefaulted. If the security descriptor contains an owner, 362 * the function sets the pointer pointed to by pOwner to the address of the security descriptor's owner SID 363 * and provides a valid value for the variable pointed to by lpbOwnerDefaulted. 364 * @param lpbOwnerDefaulted 365 * A pointer to a flag that is set to the value of the SE_OWNER_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL 366 * structure when the function returns. If the value stored in the variable pointed to by the pOwner parameter is 367 * NULL, no value is set. 368 * @return If the function succeeds, the return value is nonzero. If the 369 * function fails, the return value is zero. For extended error 370 * information, call GetLastError. 371 */ GetSecurityDescriptorOwner(SECURITY_DESCRIPTOR pSecurityDescriptor, PSIDByReference pOwner, BOOLByReference lpbOwnerDefaulted)372 boolean GetSecurityDescriptorOwner(SECURITY_DESCRIPTOR pSecurityDescriptor, PSIDByReference pOwner, BOOLByReference lpbOwnerDefaulted); 373 374 /** 375 * The SetSecurityDescriptorOwner function sets the owner information of an absolute-format security descriptor. It replaces 376 * any owner information already present in the security descriptor. 377 * @param pSecurityDescriptor 378 * A pointer to the SECURITY_DESCRIPTOR structure whose owner is set by this function. The function replaces any existing 379 * owner with the new owner. 380 * @param pOwner 381 * A pointer to a SID structure for the security descriptor's new primary owner. The SID structure is referenced by, not 382 * copied into, the security descriptor. If this parameter is NULL, the function clears the security descriptor's owner 383 * information. This marks the security descriptor as having no owner. 384 * @param bOwnerDefaulted 385 * Indicates whether the owner information is derived from a default mechanism. If this value is TRUE, it is default information. 386 * The function stores this value as the SE_OWNER_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure. If this parameter 387 * is zero, the SE_OWNER_DEFAULTED flag is cleared. 388 * @return If the function succeeds, the return value is nonzero. If the 389 * function fails, the return value is zero. For extended error 390 * information, call GetLastError. 391 */ SetSecurityDescriptorOwner(SECURITY_DESCRIPTOR pSecurityDescriptor, PSID pOwner, boolean bOwnerDefaulted)392 boolean SetSecurityDescriptorOwner(SECURITY_DESCRIPTOR pSecurityDescriptor, PSID pOwner, boolean bOwnerDefaulted); 393 394 /** 395 * The GetSecurityDescriptorGroup function retrieves the primary group information from a security descriptor. 396 * @param pSecurityDescriptor 397 * A pointer to a SECURITY_DESCRIPTOR structure whose primary group information the function retrieves. 398 * @param pGroup 399 * A pointer to a pointer to a security identifier (SID) that identifies the primary group when the function 400 * returns. If the security descriptor does not contain a primary group, the function sets the pointer 401 * pointed to by pGroup to NULL and ignores the remaining output parameter, lpbGroupDefaulted. If the 402 * security descriptor contains a primary group, the function sets the pointer pointed to by pGroup to the 403 * address of the security descriptor's group SID and provides a valid value for the variable pointed to 404 * by lpbGroupDefaulted. 405 * @param lpbGroupDefaulted 406 * A pointer to a flag that is set to the value of the SE_GROUP_DEFAULTED flag in the 407 * SECURITY_DESCRIPTOR_CONTROL structure when the function returns. If the value stored in the variable 408 * pointed to by the pGroup parameter is NULL, no value is set. 409 * @return If the function succeeds, the return value is nonzero. If the 410 * function fails, the return value is zero. For extended error 411 * information, call GetLastError. 412 */ GetSecurityDescriptorGroup(SECURITY_DESCRIPTOR pSecurityDescriptor, PSIDByReference pGroup, BOOLByReference lpbGroupDefaulted)413 boolean GetSecurityDescriptorGroup(SECURITY_DESCRIPTOR pSecurityDescriptor, PSIDByReference pGroup, BOOLByReference lpbGroupDefaulted); 414 415 /** 416 * The SetSecurityDescriptorGroup function sets the primary group information of an absolute-format security descriptor, replacing 417 * any primary group information already present in the security descriptor. 418 * @param pSecurityDescriptor 419 * A pointer to the SECURITY_DESCRIPTOR structure whose primary group is set by this function. The function replaces 420 * any existing primary group with the new primary group. 421 * @param pGroup 422 * A pointer to a SID structure for the security descriptor's new primary group. The SID structure is referenced by, not copied 423 * into, the security descriptor. If this parameter is NULL, the function clears the security descriptor's primary group 424 * information. This marks the security descriptor as having no primary group. 425 * @param bGroupDefaulted 426 * Indicates whether the primary group information was derived from a default mechanism. If this value is TRUE, it is default 427 * information, and the function stores this value as the SE_GROUP_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure. 428 * If this parameter is zero, the SE_GROUP_DEFAULTED flag is cleared. 429 * @return If the function succeeds, the return value is nonzero. If the 430 * function fails, the return value is zero. For extended error 431 * information, call GetLastError. 432 */ SetSecurityDescriptorGroup(SECURITY_DESCRIPTOR pSecurityDescriptor, PSID pGroup, boolean bGroupDefaulted)433 boolean SetSecurityDescriptorGroup(SECURITY_DESCRIPTOR pSecurityDescriptor, PSID pGroup, boolean bGroupDefaulted); 434 435 /** 436 * The GetSecurityDescriptorDacl function retrieves a pointer to the discretionary access control list (DACL) in 437 * a specified security descriptor. 438 * @param pSecurityDescriptor 439 * A pointer to the SECURITY_DESCRIPTOR structure that contains the DACL. The function retrieves a pointer to it. 440 * @param bDaclPresent 441 * A pointer to a value that indicates the presence of a DACL in the specified security descriptor. If 442 * lpbDaclPresent is TRUE, the security descriptor contains a DACL, and the remaining output parameters in this 443 * function receive valid values. If lpbDaclPresent is FALSE, the security descriptor does not contain a DACL, 444 * and the remaining output parameters do not receive valid values. A value of TRUE for lpbDaclPresent does not 445 * mean that pDacl is not NULL. That is, lpbDaclPresent can be TRUE while pDacl is NULL, meaning that a NULL 446 * DACL is in effect. A NULL DACL implicitly allows all access to an object and is not the same as an empty DACL. 447 * An empty DACL permits no access to an object. For information about creating a proper DACL, see Creating a DACL. 448 * @param pDacl 449 * A pointer to a pointer to an access control list (ACL). If a DACL exists, the function sets the pointer pointed 450 * to by pDacl to the address of the security descriptor's DACL. If a DACL does not exist, no value is stored. 451 * If the function stores a NULL value in the pointer pointed to by pDacl, the security descriptor has a NULL DACL. 452 * A NULL DACL implicitly allows all access to an object. 453 * If an application expects a non-NULL DACL but encounters a NULL DACL, the application should fail securely and 454 * not allow access. 455 * @param bDaclDefaulted 456 * A pointer to a flag set to the value of the SE_DACL_DEFAULTED flag in the SECURITY_DESCRIPTOR_CONTROL structure 457 * if a DACL exists for the security descriptor. If this flag is TRUE, the DACL was retrieved by a default mechanism; 458 * if FALSE, the DACL was explicitly specified by a user. 459 * @return If the function succeeds, the return value is nonzero. If the 460 * function fails, the return value is zero. For extended error 461 * information, call GetLastError. 462 */ GetSecurityDescriptorDacl(SECURITY_DESCRIPTOR pSecurityDescriptor, BOOLByReference bDaclPresent, PACLByReference pDacl, BOOLByReference bDaclDefaulted)463 boolean GetSecurityDescriptorDacl(SECURITY_DESCRIPTOR pSecurityDescriptor, BOOLByReference bDaclPresent, PACLByReference pDacl, BOOLByReference bDaclDefaulted); 464 465 /** 466 * The SetSecurityDescriptorDacl function sets information in a discretionary access control list (DACL). 467 * If a DACL is already present in the security descriptor, the DACL is replaced. 468 * @param pSecurityDescriptor 469 * A pointer to the SECURITY_DESCRIPTOR structure to which the function adds the DACL. This 470 * security descriptor must be in absolute format, meaning that its members must be pointers 471 * to other structures, rather than offsets to contiguous data. 472 * @param bDaclPresent 473 * A flag that indicates the presence of a DACL in the security descriptor. If this parameter 474 * is TRUE, the function sets the SE_DACL_PRESENT flag in the SECURITY_DESCRIPTOR_CONTROL 475 * structure and uses the values in the pDacl and bDaclDefaulted parameters. If this parameter 476 * is FALSE, the function clears the SE_DACL_PRESENT flag, and pDacl and bDaclDefaulted are ignored. 477 * @param pDacl 478 * A pointer to an ACL structure that specifies the DACL for the security descriptor. If this 479 * parameter is NULL, a NULL DACL is assigned to the security descriptor, which allows all access 480 * to the object. The DACL is referenced by, not copied into, the security descriptor. 481 * @param bDaclDefaulted 482 * A flag that indicates the source of the DACL. If this flag is TRUE, the DACL has been retrieved 483 * by some default mechanism. If FALSE, the DACL has been explicitly specified by a user. The function 484 * stores this value in the SE_DACL_DEFAULTED flag of the SECURITY_DESCRIPTOR_CONTROL structure. If 485 * this parameter is not specified, the SE_DACL_DEFAULTED flag is cleared. 486 * @return If the function succeeds, the return value is nonzero. If the 487 * function fails, the return value is zero. For extended error 488 * information, call GetLastError. 489 */ SetSecurityDescriptorDacl(SECURITY_DESCRIPTOR pSecurityDescriptor, boolean bDaclPresent, ACL pDacl, boolean bDaclDefaulted)490 boolean SetSecurityDescriptorDacl(SECURITY_DESCRIPTOR pSecurityDescriptor, boolean bDaclPresent, ACL pDacl, boolean bDaclDefaulted); 491 492 /** 493 * The InitializeAcl function initializes a new ACL structure. 494 * @param pAcl 495 * A pointer to an ACL structure to be initialized by this function. 496 * Allocate memory for pAcl before calling this function. 497 * @param nAclLength 498 * The length, in bytes, of the buffer pointed to by the pAcl parameter. This value 499 * must be large enough to contain the ACL header and all of the access control 500 * entries (ACEs) to be stored in the ACL. In addition, this value must be 501 * DWORD-aligned. For more information about calculating the size of an ACL, 502 * see Remarks. 503 * @param dwAclRevision 504 * The revision level of the ACL structure being created. This value can be ACL_REVISION 505 * or ACL_REVISION_DS. Use ACL_REVISION_DS if the access control list (ACL) supports 506 * object-specific ACEs. 507 * @return If the function succeeds, the return value is nonzero. If the 508 * function fails, the return value is zero. For extended error 509 * information, call GetLastError. 510 */ InitializeAcl(ACL pAcl, int nAclLength, int dwAclRevision)511 boolean InitializeAcl(ACL pAcl, int nAclLength, int dwAclRevision); 512 513 /** 514 * The AddAce function adds one or more access control entries (ACEs) to a specified access control list (ACL). 515 * @param pAcl 516 * A pointer to an ACL. This function adds an ACE to this ACL. 517 * @param dwAceRevision 518 * Specifies the revision level of the ACL being modified. This value can be ACL_REVISION or 519 * ACL_REVISION_DS. Use ACL_REVISION_DS if the ACL contains object-specific ACEs. This value 520 * must be compatible with the AceType field of all ACEs in pAceList. Otherwise, the function 521 * will fail and set the last error to ERROR_INVALID_PARAMETER. 522 * @param dwStartingAceIndex 523 * Specifies the position in the ACL's list of ACEs at which to add new ACEs. A value of zero 524 * inserts the ACEs at the beginning of the list. A value of MAXDWORD appends the ACEs to the end 525 * of the list. 526 * @param pAceList 527 * A pointer to a list of one or more ACEs to be added to the specified ACL. The ACEs in the list 528 * must be stored contiguously. 529 * @param nAceListLength 530 * Specifies the size, in bytes, of the input buffer pointed to by the pAceList parameter. 531 * @return If the function succeeds, the return value is nonzero. If the 532 * function fails, the return value is zero. For extended error 533 * information, call GetLastError. 534 */ AddAce(ACL pAcl, int dwAceRevision, int dwStartingAceIndex, Pointer pAceList, int nAceListLength)535 boolean AddAce(ACL pAcl, int dwAceRevision, int dwStartingAceIndex, Pointer pAceList, int nAceListLength); 536 537 /** 538 * The AddAce function adds one or more access control entries (ACEs) to a specified access control list (ACL). 539 * @param pAcl 540 * A pointer to an ACL. This function adds an access-allowed ACE to the end of this ACL. 541 * The ACE is in the form of an ACCESS_ALLOWED_ACE structure. 542 * @param dwAceRevision 543 * Specifies the revision level of the ACL being modified. This value can be ACL_REVISION or 544 * ACL_REVISION_DS. Use ACL_REVISION_DS if the ACL contains object-specific ACEs. 545 * @param AccessMask 546 * Specifies the mask of access rights to be granted to the specified SID. 547 * @param pSid 548 * A pointer to the SID representing a user, group, or logon account being granted access. 549 * @return If the function succeeds, the return value is nonzero. If the 550 * function fails, the return value is zero. For extended error 551 * information, call GetLastError. 552 */ AddAccessAllowedAce(ACL pAcl, int dwAceRevision, int AccessMask, PSID pSid)553 boolean AddAccessAllowedAce(ACL pAcl, int dwAceRevision, int AccessMask, PSID pSid); 554 555 /** 556 * The AddAce function adds one or more access control entries (ACEs) to a specified access control list (ACL). 557 * @param pAcl 558 * A pointer to an ACL. This function adds an access-allowed ACE to the end of this ACL. 559 * The ACE is in the form of an ACCESS_ALLOWED_ACE structure. 560 * @param dwAceRevision 561 * Specifies the revision level of the ACL being modified. This value can be ACL_REVISION or 562 * ACL_REVISION_DS. Use ACL_REVISION_DS if the ACL contains object-specific ACEs. 563 * @param AceFlags 564 * A set of bit flags that control ACE inheritance. The function sets these flags in the AceFlags 565 * member of the ACE_HEADER structure of the new ACE. This parameter can be a combination 566 * of the following values: CONTAINER_INHERIT_ACE, INHERIT_ONLY_ACE, INHERITED_ACE, 567 * NO_PROPAGATE_INHERIT_ACE, and OBJECT_INHERIT_ACE 568 * @param AccessMask 569 * Specifies the mask of access rights to be granted to the specified SID. 570 * @param pSid 571 * A pointer to the SID representing a user, group, or logon account being granted access. 572 * @return If the function succeeds, the return value is nonzero. If the 573 * function fails, the return value is zero. For extended error 574 * information, call GetLastError. 575 */ AddAccessAllowedAceEx(ACL pAcl, int dwAceRevision, int AceFlags, int AccessMask, PSID pSid)576 boolean AddAccessAllowedAceEx(ACL pAcl, int dwAceRevision, int AceFlags, int AccessMask, PSID pSid); 577 578 /** 579 * The GetAce function obtains a pointer to an access control entry (ACE) in an access 580 * control list (ACL). 581 * @param pAcl 582 * A pointer to an ACL that contains the ACE to be retrieved. 583 * @param dwAceIndex 584 * The index of the ACE to be retrieved. A value of zero corresponds to the first ACE in 585 * the ACL, a value of one to the second ACE, and so on. 586 * @param pAce 587 * A pointer to a pointer that the function sets to the address of the ACE. 588 * @return If the function succeeds, the return value is nonzero. If the 589 * function fails, the return value is zero. For extended error 590 * information, call GetLastError. 591 */ GetAce(ACL pAcl, int dwAceIndex, PointerByReference pAce)592 boolean GetAce(ACL pAcl, int dwAceIndex, PointerByReference pAce); 593 594 /** 595 * The LogonUser function attempts to log a user on to the local computer. 596 * The local computer is the computer from which LogonUser was called. You 597 * cannot use LogonUser to log on to a remote computer. You specify the user 598 * with a user name and domain, and authenticate the user with a plaintext 599 * password. If the function succeeds, you receive a handle to a token that 600 * represents the logged-on user. You can then use this token handle to 601 * impersonate the specified user or, in most cases, to create a process 602 * that runs in the context of the specified user. 603 * 604 * @param lpszUsername 605 * A pointer to a null-terminated string that specifies the name 606 * of the user. This is the name of the user account to log on 607 * to. If you use the user principal name (UPN) format, 608 * user@DNS_domain_name, the lpszDomain parameter must be NULL. 609 * @param lpszDomain 610 * A pointer to a null-terminated string that specifies the name 611 * of the domain or server whose account database contains the 612 * lpszUsername account. If this parameter is NULL, the user name 613 * must be specified in UPN format. If this parameter is ".", the 614 * function validates the account using only the local account 615 * database. 616 * @param lpszPassword 617 * A pointer to a null-terminated string that specifies the 618 * plaintext password for the user account specified by 619 * lpszUsername. 620 * @param logonType 621 * The type of logon operation to perform. 622 * @param logonProvider 623 * Specifies the logon provider. 624 * @param phToken 625 * A pointer to a handle variable that receives a handle to a 626 * token that represents the specified user. 627 * @return If the function succeeds, the function returns nonzero. If the 628 * function fails, it returns zero. To get extended error 629 * information, call GetLastError. 630 */ LogonUser(String lpszUsername, String lpszDomain, String lpszPassword, int logonType, int logonProvider, HANDLEByReference phToken)631 boolean LogonUser(String lpszUsername, String lpszDomain, 632 String lpszPassword, int logonType, int logonProvider, 633 HANDLEByReference phToken); 634 635 /** 636 * The OpenThreadToken function opens the access token associated with a 637 * thread. 638 * 639 * @param ThreadHandle 640 * Handle to the thread whose access token is opened. 641 * @param DesiredAccess 642 * Specifies an access mask that specifies the requested types of 643 * access to the access token. These requested access types are 644 * reconciled against the token's discretionary access control 645 * list (DACL) to determine which accesses are granted or denied. 646 * @param OpenAsSelf 647 * Indicates whether the access check is to be made against the 648 * security context of the thread calling the OpenThreadToken 649 * function or against the security context of the process for 650 * the calling thread. 651 * @param TokenHandle 652 * Pointer to a variable that receives the handle to the newly 653 * opened access token. 654 * @return If the function succeeds, the return value is nonzero. If the 655 * function fails, the return value is zero. To get extended error 656 * information, call GetLastError. 657 */ OpenThreadToken(HANDLE ThreadHandle, int DesiredAccess, boolean OpenAsSelf, HANDLEByReference TokenHandle)658 boolean OpenThreadToken(HANDLE ThreadHandle, int DesiredAccess, 659 boolean OpenAsSelf, HANDLEByReference TokenHandle); 660 661 /** 662 * The SetThreadToken function assigns an impersonation token to a thread. 663 * The function can also cause a thread to stop using an impersonation token. 664 * @param ThreadHandle [in, optional] 665 * A pointer to a handle to the thread to which the function 666 * assigns the impersonation token. If ThreadHandle is NULL, the 667 * function assigns the impersonation token to the calling thread. 668 * @param TokenHandle [in, optional] 669 * A handle to the impersonation token to assign to the thread. 670 * This handle must have been opened with TOKEN_IMPERSONATE access 671 * rights. For more information, see Access Rights for Access-Token 672 * Objects. If Token is NULL, the function causes the 673 * thread to stop using an impersonation token. 674 * @return If the function succeeds, the return value is nonzero. If the 675 * function fails, the return value is zero. To get extended error 676 * information, call GetLastError. 677 */ SetThreadToken(HANDLEByReference ThreadHandle, HANDLE TokenHandle)678 boolean SetThreadToken(HANDLEByReference ThreadHandle, HANDLE TokenHandle); 679 680 /** 681 * The OpenProcessToken function opens the access token associated with a 682 * process. 683 * 684 * @param ProcessHandle 685 * Handle to the process whose access token is opened. The 686 * process must have the PROCESS_QUERY_INFORMATION access 687 * permission. 688 * @param DesiredAccess 689 * Specifies an access mask that specifies the requested types of 690 * access to the access token. These requested access types are 691 * compared with the discretionary access control list (DACL) of 692 * the token to determine which accesses are granted or denied. 693 * @param TokenHandle 694 * Pointer to a handle that identifies the newly opened access 695 * token when the function returns. 696 * @return If the function succeeds, the return value is nonzero. If the 697 * function fails, the return value is zero. To get extended error 698 * information, call GetLastError. 699 */ OpenProcessToken(HANDLE ProcessHandle, int DesiredAccess, HANDLEByReference TokenHandle)700 boolean OpenProcessToken(HANDLE ProcessHandle, int DesiredAccess, 701 HANDLEByReference TokenHandle); 702 703 /** 704 * The DuplicateToken function creates a new access token that duplicates 705 * one already in existence. 706 * 707 * @param ExistingTokenHandle 708 * Handle to an access token opened with TOKEN_DUPLICATE access. 709 * @param ImpersonationLevel 710 * Specifies a SECURITY_IMPERSONATION_LEVEL enumerated type that 711 * supplies the impersonation level of the new token. 712 * @param DuplicateTokenHandle 713 * Pointer to a variable that receives a handle to the duplicate 714 * token. This handle has TOKEN_IMPERSONATE and TOKEN_QUERY 715 * access to the new token. 716 * @return If the function succeeds, the return value is nonzero. If the 717 * function fails, the return value is zero. To get extended error 718 * information, call GetLastError. 719 */ DuplicateToken(HANDLE ExistingTokenHandle, int ImpersonationLevel, HANDLEByReference DuplicateTokenHandle)720 boolean DuplicateToken(HANDLE ExistingTokenHandle, 721 int ImpersonationLevel, HANDLEByReference DuplicateTokenHandle); 722 723 /** 724 * The DuplicateTokenEx function creates a new access token that duplicates 725 * an existing token. This function can create either a primary token or an 726 * impersonation token. 727 * 728 * @param hExistingToken 729 * A handle to an access token opened with TOKEN_DUPLICATE 730 * access. 731 * @param dwDesiredAccess 732 * Specifies the requested access rights for the new token. 733 * @param lpTokenAttributes 734 * A pointer to a SECURITY_ATTRIBUTES structure that specifies a 735 * security descriptor for the new token and determines whether 736 * child processes can inherit the token. 737 * @param ImpersonationLevel 738 * Specifies a value from the SECURITY_IMPERSONATION_LEVEL 739 * enumeration that indicates the impersonation level of the new 740 * token. 741 * @param TokenType 742 * Specifies one of the following values from the TOKEN_TYPE 743 * enumeration. 744 * @param phNewToken 745 * A pointer to a HANDLE variable that receives the new token. 746 * @return If the function succeeds, the function returns a nonzero value. 747 * If the function fails, it returns zero. To get extended error 748 * information, call GetLastError. 749 */ DuplicateTokenEx(HANDLE hExistingToken, int dwDesiredAccess, WinBase.SECURITY_ATTRIBUTES lpTokenAttributes, int ImpersonationLevel, int TokenType, HANDLEByReference phNewToken)750 boolean DuplicateTokenEx(HANDLE hExistingToken, int dwDesiredAccess, 751 WinBase.SECURITY_ATTRIBUTES lpTokenAttributes, 752 int ImpersonationLevel, int TokenType, HANDLEByReference phNewToken); 753 754 /** 755 * Retrieves a specified type of information about an access token. The 756 * calling process must have appropriate access rights to obtain the 757 * information. 758 * 759 * @param tokenHandle 760 * Handle to an access token from which information is retrieved. 761 * If TokenInformationClass specifies TokenSource, the handle 762 * must have TOKEN_QUERY_SOURCE access. For all other 763 * TokenInformationClass values, the handle must have TOKEN_QUERY 764 * access. 765 * @param tokenInformationClass 766 * Specifies a value from the TOKEN_INFORMATION_CLASS enumerated 767 * type to identify the type of information the function 768 * retrieves. 769 * @param tokenInformation 770 * Pointer to a buffer the function fills with the requested 771 * information. The structure put into this buffer depends upon 772 * the type of information specified by the TokenInformationClass 773 * parameter. 774 * @param tokenInformationLength 775 * Specifies the size, in bytes, of the buffer pointed to by the 776 * TokenInformation parameter. If TokenInformation is NULL, this 777 * parameter must be zero. 778 * @param returnLength 779 * Pointer to a variable that receives the number of bytes needed 780 * for the buffer pointed to by the TokenInformation parameter. 781 * If this value is larger than the value specified in the 782 * TokenInformationLength parameter, the function fails and 783 * stores no data in the buffer. 784 * @return If the function succeeds, the return value is nonzero. If the 785 * function fails, the return value is zero. To get extended error 786 * information, call GetLastError. 787 */ GetTokenInformation(HANDLE tokenHandle, int tokenInformationClass, Structure tokenInformation, int tokenInformationLength, IntByReference returnLength)788 boolean GetTokenInformation(HANDLE tokenHandle, 789 int tokenInformationClass, Structure tokenInformation, 790 int tokenInformationLength, IntByReference returnLength); 791 792 /** 793 * The ImpersonateLoggedOnUser function lets the calling thread impersonate 794 * the security context of a logged-on user. The user is represented by a 795 * token handle. 796 * 797 * @param hToken 798 * Handle to a primary or impersonation access token that 799 * represents a logged-on user. This can be a token handle 800 * returned by a call to LogonUser, CreateRestrictedToken, 801 * DuplicateToken, DuplicateTokenEx, OpenProcessToken, or 802 * OpenThreadToken functions. If hToken is a primary token, it 803 * must have TOKEN_QUERY and TOKEN_DUPLICATE access. If hToken is 804 * an impersonation token, it must have TOKEN_QUERY and 805 * TOKEN_IMPERSONATE access. 806 * @return If the function succeeds, the return value is nonzero. 807 */ ImpersonateLoggedOnUser(HANDLE hToken)808 boolean ImpersonateLoggedOnUser(HANDLE hToken); 809 810 /** 811 * The ImpersonateSelf function obtains an access token that impersonates 812 * the security context of the calling process. The token is assigned to the 813 * calling thread. 814 * 815 * @param ImpersonationLevel 816 * Specifies a SECURITY_IMPERSONATION_LEVEL enumerated type that 817 * supplies the impersonation level of the new token. 818 * @return If the function succeeds, the return value is nonzero. 819 */ ImpersonateSelf(int ImpersonationLevel)820 boolean ImpersonateSelf(int ImpersonationLevel); 821 822 /** 823 * The RevertToSelf function terminates the impersonation of a client 824 * application. 825 * 826 * @return If the function succeeds, the return value is nonzero. 827 */ RevertToSelf()828 boolean RevertToSelf(); 829 830 /** 831 * The RegOpenKeyEx function opens the specified registry key. Note that key 832 * names are not case sensitive. 833 * 834 * @param hKey 835 * Handle to an open key. 836 * @param lpSubKey 837 * Pointer to a null-terminated string containing the name of the 838 * subkey to open. 839 * @param ulOptions 840 * Reserved; must be zero. 841 * @param samDesired 842 * Access mask that specifies the desired access rights to the 843 * key. The function fails if the security descriptor of the key 844 * does not permit the requested access for the calling process. 845 * @param phkResult 846 * Pointer to a variable that receives a handle to the opened 847 * key. If the key is not one of the predefined registry keys, 848 * call the RegCloseKey function after you have finished using 849 * the handle. 850 * @return If the function succeeds, the return value is ERROR_SUCCESS. If 851 * the function fails, the return value is a nonzero error code 852 * defined in Winerror.h. 853 */ RegOpenKeyEx(HKEY hKey, String lpSubKey, int ulOptions, int samDesired, HKEYByReference phkResult)854 int RegOpenKeyEx(HKEY hKey, String lpSubKey, int ulOptions, 855 int samDesired, HKEYByReference phkResult); 856 857 /** 858 * Establishes a connection to a predefined registry key on another 859 * computer. 860 * @param lpMachineName 861 * The name of the remote computer. The string has 862 * the following form:<br /> 863 * <pre><code>\\computername</code></pre> 864 * The caller must have access to the remote computer or the 865 * function fails.<br /> 866 * If this parameter is <c>null</c>, the local computer name 867 * is used. 868 * @param hKey 869 * A predefined registry handle. This parameter can be one of 870 * the following predefined keys on the remote computer.<br /> 871 * <ul> 872 * <li>{@link WinReg#HKEY_LOCAL_MACHINE}</li> 873 * <li>{@link WinReg#HKEY_PERFORMANCE_DATA}</li> 874 * <li>{@link WinReg#HKEY_USERS}</li> 875 * </ul> 876 * @param phkResult 877 * A pointer to a variable that receives a key handle 878 * identifying the predefined handle on the remote computer. 879 * @return If the function succeeds, the return value is 880 * {@link WinError#ERROR_SUCCESS}.<br /> 881 * If the remote computer cannot be found or if its Remote Registry 882 * service is disabled, the function fails and returns 883 * {@link WinError#ERROR_BAD_NETPATH}.<br /> 884 * If attempting to use a registry handle other than one of the 885 * three predefined handles, the function fails and returns 886 * {@link WinError#ERROR_INVALID_HANDLE}.<br /> 887 * If access to the registry is denied, the function fails and 888 * returns {@link WinError#ERROR_ACCESS_DENIED}. <br /> 889 * If the function fails for some other reason, you can use the 890 * {@link Native#getLastError} method to get a generic description 891 * of the error. 892 * @see <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms724840.aspx">RegConnectRegistry function (Windows)</a> 893 * @see <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms724836.aspx">Predefined Keys (Windows)</a> 894 */ RegConnectRegistry(String lpMachineName, HKEY hKey, HKEYByReference phkResult)895 int RegConnectRegistry(String lpMachineName, HKEY hKey, HKEYByReference phkResult); 896 897 /** 898 * The RegQueryValueEx function retrieves the type and data for a specified 899 * value name associated with an open registry key. 900 * 901 * @param hKey 902 * Handle to an open key. The key must have been opened with the 903 * KEY_QUERY_VALUE access right. 904 * @param lpValueName 905 * Pointer to a null-terminated string containing the name of the 906 * value to query. If lpValueName is NULL or an empty string, "", 907 * the function retrieves the type and data for the key's unnamed 908 * or default value, if any. 909 * @param lpReserved 910 * Reserved; must be NULL. 911 * @param lpType 912 * Pointer to a variable that receives a code indicating the type 913 * of data stored in the specified value. 914 * @param lpData 915 * Pointer to a buffer that receives the value's data. This 916 * parameter can be NULL if the data is not required. If the data 917 * is a string, the function checks for a terminating null 918 * character. If one is not found, the string is stored with a 919 * null terminator if the buffer is large enough to accommodate 920 * the extra character. Otherwise, the string is stored as is. 921 * @param lpcbData 922 * Pointer to a variable that specifies the size of the buffer 923 * pointed to by the lpData parameter, in bytes. When the 924 * function returns, this variable contains the size of the data 925 * copied to lpData. The lpcbData parameter can be NULL only if 926 * lpData is NULL. If the data has the REG_SZ, REG_MULTI_SZ or 927 * REG_EXPAND_SZ type, this size includes any terminating null 928 * character or characters. If the buffer specified by lpData 929 * parameter is not large enough to hold the data, the function 930 * returns ERROR_MORE_DATA and stores the required buffer size in 931 * the variable pointed to by lpcbData. In this case, the 932 * contents of the lpData buffer are undefined. If lpData is 933 * NULL, and lpcbData is non-NULL, the function returns 934 * ERROR_SUCCESS and stores the size of the data, in bytes, in 935 * the variable pointed to by lpcbData. This enables an 936 * application to determine the best way to allocate a buffer for 937 * the value's data. 938 * @return If the function succeeds, the return value is ERROR_SUCCESS. If 939 * the function fails, the return value is a nonzero error code 940 * defined in Winerror.h. 941 */ RegQueryValueEx(HKEY hKey, String lpValueName, int lpReserved, IntByReference lpType, char[] lpData, IntByReference lpcbData)942 int RegQueryValueEx(HKEY hKey, String lpValueName, int lpReserved, 943 IntByReference lpType, char[] lpData, IntByReference lpcbData); 944 RegQueryValueEx(HKEY hKey, String lpValueName, int lpReserved, IntByReference lpType, byte[] lpData, IntByReference lpcbData)945 int RegQueryValueEx(HKEY hKey, String lpValueName, int lpReserved, 946 IntByReference lpType, byte[] lpData, IntByReference lpcbData); 947 RegQueryValueEx(HKEY hKey, String lpValueName, int lpReserved, IntByReference lpType, IntByReference lpData, IntByReference lpcbData)948 int RegQueryValueEx(HKEY hKey, String lpValueName, int lpReserved, 949 IntByReference lpType, IntByReference lpData, 950 IntByReference lpcbData); 951 RegQueryValueEx(HKEY hKey, String lpValueName, int lpReserved, IntByReference lpType, LongByReference lpData, IntByReference lpcbData)952 int RegQueryValueEx(HKEY hKey, String lpValueName, int lpReserved, 953 IntByReference lpType, LongByReference lpData, 954 IntByReference lpcbData); 955 RegQueryValueEx(HKEY hKey, String lpValueName, int lpReserved, IntByReference lpType, Pointer lpData, IntByReference lpcbData)956 int RegQueryValueEx(HKEY hKey, String lpValueName, int lpReserved, 957 IntByReference lpType, Pointer lpData, IntByReference lpcbData); 958 959 /** 960 * The RegCloseKey function releases a handle to the specified registry key. 961 * 962 * @param hKey 963 * Handle to the open key to be closed. The handle must have been 964 * opened by the RegCreateKeyEx, RegOpenKeyEx, or 965 * RegConnectRegistry function. 966 * @return If the function succeeds, the return value is ERROR_SUCCESS. If 967 * the function fails, the return value is a nonzero error code 968 * defined in Winerror.h. 969 */ RegCloseKey(HKEY hKey)970 int RegCloseKey(HKEY hKey); 971 972 /** 973 * The RegDeleteValue function removes a named value from the specified 974 * registry key. Note that value names are not case sensitive. 975 * 976 * @param hKey 977 * Handle to an open key. The key must have been opened with the 978 * KEY_SET_VALUE access right. 979 * @param lpValueName 980 * Pointer to a null-terminated string that names the value to 981 * remove. If this parameter is NULL or an empty string, the 982 * value set by the RegSetValue function is removed. 983 * @return If the function succeeds, the return value is ERROR_SUCCESS. If 984 * the function fails, the return value is a nonzero error code 985 * defined in Winerror.h. 986 */ RegDeleteValue(HKEY hKey, String lpValueName)987 int RegDeleteValue(HKEY hKey, String lpValueName); 988 989 /** 990 * The RegSetValueEx function sets the data and type of a specified value 991 * under a registry key. 992 * 993 * @param hKey 994 * Handle to an open key. The key must have been opened with the 995 * KEY_SET_VALUE access right. 996 * @param lpValueName 997 * Pointer to a string containing the name of the value to set. 998 * If a value with this name is not already present in the key, 999 * the function adds it to the key. If lpValueName is NULL or an 1000 * empty string, "", the function sets the type and data for the 1001 * key's unnamed or default value. 1002 * @param Reserved 1003 * Reserved; must be zero. 1004 * @param dwType 1005 * Type of data pointed to by the lpData parameter. 1006 * @param lpData 1007 * Pointer to a buffer containing the data to be stored with the 1008 * specified value name. 1009 * @param cbData 1010 * Size of the information pointed to by the lpData parameter, in 1011 * bytes. If the data is of type REG_SZ, REG_EXPAND_SZ, or 1012 * REG_MULTI_SZ, cbData must include the size of the terminating 1013 * null character or characters. 1014 * @return If the function succeeds, the return value is ERROR_SUCCESS. If 1015 * the function fails, the return value is a nonzero error code 1016 * defined in Winerror.h. 1017 */ RegSetValueEx(HKEY hKey, String lpValueName, int Reserved, int dwType, Pointer lpData, int cbData)1018 int RegSetValueEx(HKEY hKey, String lpValueName, int Reserved, 1019 int dwType, Pointer lpData, int cbData); 1020 1021 /** 1022 * See {@link #RegSetValueEx(com.sun.jna.platform.win32.WinReg.HKEY, java.lang.String, int, int, com.sun.jna.Pointer, int) } 1023 */ RegSetValueEx(HKEY hKey, String lpValueName, int Reserved, int dwType, char[] lpData, int cbData)1024 int RegSetValueEx(HKEY hKey, String lpValueName, int Reserved, 1025 int dwType, char[] lpData, int cbData); 1026 1027 /** 1028 * See {@link #RegSetValueEx(com.sun.jna.platform.win32.WinReg.HKEY, java.lang.String, int, int, com.sun.jna.Pointer, int) } 1029 */ RegSetValueEx(HKEY hKey, String lpValueName, int Reserved, int dwType, byte[] lpData, int cbData)1030 int RegSetValueEx(HKEY hKey, String lpValueName, int Reserved, 1031 int dwType, byte[] lpData, int cbData); 1032 1033 /** 1034 * 1035 * @param hKey registry key 1036 * @param lpSubKey subkey name 1037 * @param Reserved unused 1038 * @param lpClass class 1039 * @param dwOptions options 1040 * @param samDesired ? 1041 * @param lpSecurityAttributes security attributes 1042 * @param phkResult resulting key 1043 * @param lpdwDisposition ? 1044 * @return If the function succeeds, the return value is ERROR_SUCCESS. If 1045 * the function fails, the return value is a nonzero error code 1046 * defined in Winerror.h. 1047 */ RegCreateKeyEx(HKEY hKey, String lpSubKey, int Reserved, String lpClass, int dwOptions, int samDesired, SECURITY_ATTRIBUTES lpSecurityAttributes, HKEYByReference phkResult, IntByReference lpdwDisposition)1048 int RegCreateKeyEx(HKEY hKey, String lpSubKey, int Reserved, 1049 String lpClass, int dwOptions, int samDesired, 1050 SECURITY_ATTRIBUTES lpSecurityAttributes, 1051 HKEYByReference phkResult, IntByReference lpdwDisposition); 1052 1053 /** 1054 * 1055 * @param hKey registry key 1056 * @param name key name 1057 * @return If the function succeeds, the return value is ERROR_SUCCESS. If 1058 * the function fails, the return value is a nonzero error code 1059 * defined in Winerror.h. 1060 */ RegDeleteKey(HKEY hKey, String name)1061 int RegDeleteKey(HKEY hKey, String name); 1062 1063 /** 1064 * The RegEnumKeyEx function enumerates subkeys of the specified open 1065 * registry key. The function retrieves information about one subkey each 1066 * time it is called. 1067 * 1068 * @param hKey 1069 * Handle to an open key. The key must have been opened with the 1070 * KEY_ENUMERATE_SUB_KEYS access right. 1071 * @param dwIndex 1072 * Index of the subkey to retrieve. This parameter should be zero 1073 * for the first call to the RegEnumKeyEx function and then 1074 * incremented for subsequent calls. Because subkeys are not 1075 * ordered, any new subkey will have an arbitrary index. This 1076 * means that the function may return subkeys in any order. 1077 * @param lpName 1078 * Pointer to a buffer that receives the name of the subkey, 1079 * including the terminating null character. The function copies 1080 * only the name of the subkey, not the full key hierarchy, to 1081 * the buffer. 1082 * @param lpcName 1083 * Pointer to a variable that specifies the size of the buffer 1084 * specified by the lpName parameter, in TCHARs. This size should 1085 * include the terminating null character. When the function 1086 * returns, the variable pointed to by lpcName contains the 1087 * number of characters stored in the buffer. The count returned 1088 * does not include the terminating null character. 1089 * @param reserved 1090 * Reserved; must be NULL. 1091 * @param lpClass 1092 * Pointer to a buffer that receives the null-terminated class 1093 * string of the enumerated subkey. This parameter can be NULL. 1094 * @param lpcClass 1095 * Pointer to a variable that specifies the size of the buffer 1096 * specified by the lpClass parameter, in TCHARs. The size should 1097 * include the terminating null character. When the function 1098 * returns, lpcClass contains the number of characters stored in 1099 * the buffer. The count returned does not include the 1100 * terminating null character. This parameter can be NULL only if 1101 * lpClass is NULL. 1102 * @param lpftLastWriteTime 1103 * Pointer to a variable that receives the time at which the 1104 * enumerated subkey was last written. 1105 * @return If the function succeeds, the return value is ERROR_SUCCESS. If 1106 * the function fails, the return value is a nonzero error code 1107 * defined in Winerror.h. 1108 */ RegEnumKeyEx(HKEY hKey, int dwIndex, char[] lpName, IntByReference lpcName, IntByReference reserved, char[] lpClass, IntByReference lpcClass, WinBase.FILETIME lpftLastWriteTime)1109 int RegEnumKeyEx(HKEY hKey, int dwIndex, char[] lpName, 1110 IntByReference lpcName, IntByReference reserved, char[] lpClass, 1111 IntByReference lpcClass, WinBase.FILETIME lpftLastWriteTime); 1112 1113 /** 1114 * The RegEnumValue function enumerates the values for the specified open 1115 * registry key. The function copies one indexed value name and data block 1116 * for the key each time it is called. 1117 * 1118 * @param hKey 1119 * Handle to an open key. The key must have been opened with the 1120 * KEY_QUERY_VALUE access right. 1121 * @param dwIndex 1122 * Index of the value to be retrieved. This parameter should be 1123 * zero for the first call to the RegEnumValue function and then 1124 * be incremented for subsequent calls. Because values are not 1125 * ordered, any new value will have an arbitrary index. This 1126 * means that the function may return values in any order. 1127 * @param lpValueName 1128 * Pointer to a buffer that receives the name of the value, 1129 * including the terminating null character. 1130 * @param lpcchValueName 1131 * Pointer to a variable that specifies the size of the buffer 1132 * pointed to by the lpValueName parameter, in TCHARs. This size 1133 * should include the terminating null character. When the 1134 * function returns, the variable pointed to by lpcValueName 1135 * contains the number of characters stored in the buffer. The 1136 * count returned does not include the terminating null 1137 * character. 1138 * @param reserved 1139 * Reserved; must be NULL. 1140 * @param lpType 1141 * Pointer to a variable that receives a code indicating the type 1142 * of data stored in the specified value. 1143 * @param lpData 1144 * Pointer to a buffer that receives the data for the value 1145 * entry. This parameter can be NULL if the data is not required. 1146 * @param lpcbData 1147 * Pointer to a variable that specifies the size of the buffer 1148 * pointed to by the lpData parameter, in bytes. 1149 * @return If the function succeeds, the return value is ERROR_SUCCESS. If 1150 * the function fails, the return value is a nonzero error code 1151 * defined in Winerror.h. 1152 */ RegEnumValue(HKEY hKey, int dwIndex, char[] lpValueName, IntByReference lpcchValueName, IntByReference reserved, IntByReference lpType, Pointer lpData, IntByReference lpcbData)1153 int RegEnumValue(HKEY hKey, int dwIndex, char[] lpValueName, 1154 IntByReference lpcchValueName, IntByReference reserved, 1155 IntByReference lpType, Pointer lpData, IntByReference lpcbData); 1156 1157 /** 1158 * See {@link #RegEnumValue(com.sun.jna.platform.win32.WinReg.HKEY, int, char[], com.sun.jna.ptr.IntByReference, com.sun.jna.ptr.IntByReference, com.sun.jna.ptr.IntByReference, com.sun.jna.Pointer, com.sun.jna.ptr.IntByReference)}. 1159 */ RegEnumValue(HKEY hKey, int dwIndex, char[] lpValueName, IntByReference lpcchValueName, IntByReference reserved, IntByReference lpType, byte[] lpData, IntByReference lpcbData)1160 int RegEnumValue(HKEY hKey, int dwIndex, char[] lpValueName, 1161 IntByReference lpcchValueName, IntByReference reserved, 1162 IntByReference lpType, byte[] lpData, IntByReference lpcbData); 1163 1164 /** 1165 * The RegQueryInfoKey function retrieves information about the specified 1166 * registry key. 1167 * 1168 * @param hKey 1169 * A handle to an open key. The key must have been opened with 1170 * the KEY_QUERY_VALUE access right. 1171 * @param lpClass 1172 * A pointer to a buffer that receives the null-terminated class 1173 * string of the key. This parameter can be ignored. This 1174 * parameter can be NULL. 1175 * @param lpcClass 1176 * A pointer to a variable that specifies the size of the buffer 1177 * pointed to by the lpClass parameter, in characters. 1178 * @param lpReserved 1179 * Reserved; must be NULL. 1180 * @param lpcSubKeys 1181 * A pointer to a variable that receives the number of subkeys 1182 * that are contained by the specified key. This parameter can be 1183 * NULL. 1184 * @param lpcMaxSubKeyLen 1185 * A pointer to a variable that receives the size of the key's 1186 * subkey with the longest name, in characters, not including the 1187 * terminating null character. This parameter can be NULL. 1188 * @param lpcMaxClassLen 1189 * A pointer to a variable that receives the size of the longest 1190 * string that specifies a subkey class, in characters. The count 1191 * returned does not include the terminating null character. This 1192 * parameter can be NULL. 1193 * @param lpcValues 1194 * A pointer to a variable that receives the number of values 1195 * that are associated with the key. This parameter can be NULL. 1196 * @param lpcMaxValueNameLen 1197 * A pointer to a variable that receives the size of the key's 1198 * longest value name, in characters. The size does not include 1199 * the terminating null character. This parameter can be NULL. 1200 * @param lpcMaxValueLen 1201 * A pointer to a variable that receives the size of the longest 1202 * data component among the key's values, in bytes. This 1203 * parameter can be NULL. 1204 * @param lpcbSecurityDescriptor 1205 * A pointer to a variable that receives the size of the key's 1206 * security descriptor, in bytes. This parameter can be NULL. 1207 * @param lpftLastWriteTime 1208 * A pointer to a FILETIME structure that receives the last write 1209 * time. This parameter can be NULL. 1210 * @return If the function succeeds, the return value is ERROR_SUCCESS. If 1211 * the function fails, the return value is a nonzero error code 1212 * defined in Winerror.h. 1213 */ RegQueryInfoKey(HKEY hKey, char[] lpClass, IntByReference lpcClass, IntByReference lpReserved, IntByReference lpcSubKeys, IntByReference lpcMaxSubKeyLen, IntByReference lpcMaxClassLen, IntByReference lpcValues, IntByReference lpcMaxValueNameLen, IntByReference lpcMaxValueLen, IntByReference lpcbSecurityDescriptor, WinBase.FILETIME lpftLastWriteTime)1214 int RegQueryInfoKey(HKEY hKey, char[] lpClass, 1215 IntByReference lpcClass, IntByReference lpReserved, 1216 IntByReference lpcSubKeys, IntByReference lpcMaxSubKeyLen, 1217 IntByReference lpcMaxClassLen, IntByReference lpcValues, 1218 IntByReference lpcMaxValueNameLen, IntByReference lpcMaxValueLen, 1219 IntByReference lpcbSecurityDescriptor, 1220 WinBase.FILETIME lpftLastWriteTime); 1221 1222 /** 1223 * Retrieves the type and data for the specified registry value. 1224 * 1225 * @param hkey 1226 * [in] A handle to an open registry key. The key must have been 1227 * opened with the KEY_QUERY_VALUE access right. For more 1228 * information, see Registry Key Security and Access Rights. 1229 * 1230 * This handle is returned by the RegCreateKeyEx, 1231 * RegCreateKeyTransacted, RegOpenKeyEx, or RegOpenKeyTransacted 1232 * function. It can also be one of the following predefined keys: 1233 * 1234 * HKEY_CLASSES_ROOT HKEY_CURRENT_CONFIG HKEY_CURRENT_USER 1235 * HKEY_LOCAL_MACHINE HKEY_PERFORMANCE_DATA 1236 * HKEY_PERFORMANCE_NLSTEXT HKEY_PERFORMANCE_TEXT HKEY_USERS 1237 * 1238 * @param lpSubKey 1239 * [in, optional] The name of the registry key. This key must be 1240 * a subkey of the key specified by the hkey parameter. 1241 * 1242 * Key names are not case sensitive. 1243 * 1244 * @param lpValue 1245 * [in, optional] 1246 * 1247 * The name of the registry value. 1248 * 1249 * If this parameter is NULL or an empty string, "", the function 1250 * retrieves the type and data for the key's unnamed or default 1251 * value, if any. 1252 * 1253 * For more information, see Registry Element Size Limits. 1254 * 1255 * Keys do not automatically have an unnamed or default value. 1256 * Unnamed values can be of any type. 1257 * 1258 * @param dwFlags 1259 * [in, optional] 1260 * 1261 * The flags that restrict the data type of value to be queried. 1262 * If the data type of the value does not meet this criteria, the 1263 * function fails. This parameter can be one or more of the 1264 * following values. 1265 * 1266 * RRF_RT_ANY 0x0000ffff No type restriction. RRF_RT_DWORD 1267 * 0x00000018 Restrict type to 32-bit 1268 * RRF_RT_REG_BINARY|RRF_RT_REG_DWORD. RRF_RT_QWORD 0x00000048 1269 * Restrict type to 64-bit RRF_RT_REG_BINARY | RRF_RT_REG_DWORD. 1270 * RRF_RT_REG_BINARY 0x00000008 Restrict type to REG_BINARY. 1271 * RRF_RT_REG_DWORD 0x00000010 Restrict type to REG_DWORD. 1272 * RRF_RT_REG_EXPAND_SZ 0x00000004 Restrict type to 1273 * REG_EXPAND_SZ. RRF_RT_REG_MULTI_SZ 0x00000020 Restrict type to 1274 * REG_MULTI_SZ. RRF_RT_REG_NONE 0x00000001 Restrict type to 1275 * REG_NONE. RRF_RT_REG_QWORD 0x00000040 Restrict type to 1276 * REG_QWORD. RRF_RT_REG_SZ 0x00000002 Restrict type to REG_SZ. 1277 * 1278 * This parameter can also include one or more of the following 1279 * values. RRF_NOEXPAND 0x10000000 1280 * 1281 * Do not automatically expand environment strings if the value 1282 * is of type REG_EXPAND_SZ. 1283 * 1284 * RRF_ZEROONFAILURE 0x20000000 1285 * 1286 * If pvData is not NULL, set the contents of the buffer to 1287 * zeroes on failure. 1288 * 1289 * @param pdwType 1290 * [out, optional] 1291 * 1292 * A pointer to a variable that receives a code indicating the 1293 * type of data stored in the specified value. For a list of the 1294 * possible type codes, see Registry Value Types. This parameter 1295 * can be NULL if the type is not required. 1296 * 1297 * @param pvData 1298 * [out, optional] 1299 * 1300 * A pointer to a buffer that receives the value's data. This 1301 * parameter can be NULL if the data is not required. 1302 * 1303 * If the data is a string, the function checks for a terminating 1304 * null character. If one is not found, the string is stored with 1305 * a null terminator if the buffer is large enough to accommodate 1306 * the extra character. Otherwise, the function fails and returns 1307 * ERROR_MORE_DATA. 1308 * 1309 * @param pcbData 1310 * [in, out, optional] 1311 * 1312 * A pointer to a variable that specifies the size of the buffer 1313 * pointed to by the pvData parameter, in bytes. When the 1314 * function returns, this variable contains the size of the data 1315 * copied to pvData. 1316 * 1317 * The pcbData parameter can be NULL only if pvData is NULL. 1318 * 1319 * If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ 1320 * type, this size includes any terminating null character or 1321 * characters. For more information, see Remarks. 1322 * 1323 * If the buffer specified by pvData parameter is not large 1324 * enough to hold the data, the function returns ERROR_MORE_DATA 1325 * and stores the required buffer size in the variable pointed to 1326 * by pcbData. In this case, the contents of the pvData buffer 1327 * are undefined. 1328 * 1329 * If pvData is NULL, and pcbData is non-NULL, the function 1330 * returns ERROR_SUCCESS and stores the size of the data, in 1331 * bytes, in the variable pointed to by pcbData. This enables an 1332 * application to determine the best way to allocate a buffer for 1333 * the value's data. 1334 * 1335 * If hKey specifies HKEY_PERFORMANCE_DATA and the pvData buffer 1336 * is not large enough to contain all of the returned data, the 1337 * function returns ERROR_MORE_DATA and the value returned 1338 * through the pcbData parameter is undefined. This is because 1339 * the size of the performance data can change from one call to 1340 * the next. In this case, you must increase the buffer size and 1341 * call RegGetValue again passing the updated buffer size in the 1342 * pcbData parameter. Repeat this until the function succeeds. 1343 * You need to maintain a separate variable to keep track of the 1344 * buffer size, because the value returned by pcbData is 1345 * unpredictable. 1346 * 1347 * Return value If the function succeeds, the return value is 1348 * ERROR_SUCCESS. If the function fails, the return value is a 1349 * system error code. If the pvData buffer is too small to 1350 * receive the value, the function returns ERROR_MORE_DATA. 1351 * @return status 1352 */ RegGetValue(HKEY hkey, String lpSubKey, String lpValue, int dwFlags, IntByReference pdwType, Pointer pvData, IntByReference pcbData)1353 int RegGetValue(HKEY hkey, String lpSubKey, String lpValue, 1354 int dwFlags, IntByReference pdwType, Pointer pvData, 1355 IntByReference pcbData); 1356 1357 /** 1358 * See {@link #RegGetValue(com.sun.jna.platform.win32.WinReg.HKEY, java.lang.String, java.lang.String, int, com.sun.jna.ptr.IntByReference, com.sun.jna.Pointer, com.sun.jna.ptr.IntByReference)}. 1359 */ RegGetValue(HKEY hkey, String lpSubKey, String lpValue, int dwFlags, IntByReference pdwType, byte[] pvData, IntByReference pcbData)1360 int RegGetValue(HKEY hkey, String lpSubKey, String lpValue, 1361 int dwFlags, IntByReference pdwType, byte[] pvData, 1362 IntByReference pcbData); 1363 1364 /** 1365 * Retrieves a registered handle to the specified event log. 1366 * 1367 * @param lpUNCServerName 1368 * The Universal Naming Convention (UNC) name of the remote 1369 * server on which this operation is to be performed. If this 1370 * parameter is NULL, the local computer is used. 1371 * @param lpSourceName 1372 * The name of the event source whose handle is to be retrieved. 1373 * The source name must be a subkey of a log under the Eventlog 1374 * registry key. However, the Security log is for system use 1375 * only. 1376 * @return If the function succeeds, the return value is a handle to the 1377 * event log. If the function fails, the return value is NULL. To 1378 * get extended error information, call GetLastError. The function 1379 * returns ERROR_ACCESS_DENIED if lpSourceName specifies the 1380 * Security event log. 1381 */ RegisterEventSource(String lpUNCServerName, String lpSourceName)1382 HANDLE RegisterEventSource(String lpUNCServerName, String lpSourceName); 1383 1384 /** 1385 * Closes the specified event log. 1386 * 1387 * @param hEventLog 1388 * A handle to the event log. The RegisterEventSource function 1389 * returns this handle. 1390 * @return If the function succeeds, the return value is nonzero. If the 1391 * function fails, the return value is zero. To get extended error 1392 * information, call GetLastError. 1393 */ DeregisterEventSource(HANDLE hEventLog)1394 boolean DeregisterEventSource(HANDLE hEventLog); 1395 1396 /** 1397 * Opens a handle to the specified event log. 1398 * 1399 * @param lpUNCServerName 1400 * The Universal Naming Convention (UNC) name of the remote 1401 * server on which the event log is to be opened. If this 1402 * parameter is NULL, the local computer is used. 1403 * @param lpSourceName 1404 * The name of the log. If you specify a custom log and it cannot 1405 * be found, the event logging service opens the Application log; 1406 * however, there will be no associated message or category 1407 * string file. 1408 * @return If the function succeeds, the return value is the handle to an 1409 * event log. If the function fails, the return value is NULL. To 1410 * get extended error information, call GetLastError. 1411 */ OpenEventLog(String lpUNCServerName, String lpSourceName)1412 HANDLE OpenEventLog(String lpUNCServerName, String lpSourceName); 1413 1414 /** 1415 * Closes the specified event log. 1416 * 1417 * @param hEventLog 1418 * A handle to the event log to be closed. The OpenEventLog or 1419 * OpenBackupEventLog function returns this handle. 1420 * @return If the function succeeds, the return value is nonzero. If the 1421 * function fails, the return value is zero. To get extended error 1422 * information, call GetLastError. 1423 */ CloseEventLog(HANDLE hEventLog)1424 boolean CloseEventLog(HANDLE hEventLog); 1425 1426 /** 1427 * Retrieves the number of records in the specified event log. 1428 * 1429 * @param hEventLog 1430 * A handle to the open event log. The OpenEventLog or 1431 * OpenBackupEventLog function returns this handle. 1432 * @param NumberOfRecords 1433 * A pointer to a variable that receives the number of records in 1434 * the specified event log. 1435 * @return If the function succeeds, the return value is nonzero. If the 1436 * function fails, the return value is zero. To get extended error 1437 * information, call GetLastError. 1438 */ GetNumberOfEventLogRecords(HANDLE hEventLog, IntByReference NumberOfRecords)1439 boolean GetNumberOfEventLogRecords(HANDLE hEventLog, IntByReference NumberOfRecords); 1440 1441 /** 1442 * Writes an entry at the end of the specified event log. 1443 * 1444 * @param hEventLog 1445 * A handle to the event log. The RegisterEventSource function 1446 * returns this handle. As of Windows XP with SP2, this parameter 1447 * cannot be a handle to the Security log. To write an event to 1448 * the Security log, use the AuthzReportSecurityEvent function. 1449 * @param wType 1450 * The type of event to be logged. 1451 * @param wCategory 1452 * The event category. This is source-specific information; the 1453 * category can have any value. 1454 * @param dwEventID 1455 * The event identifier. The event identifier specifies the entry 1456 * in the message file associated with the event source. 1457 * @param lpUserSid 1458 * A pointer to the current user's security identifier. This 1459 * parameter can be NULL if the security identifier is not 1460 * required. 1461 * @param wNumStrings 1462 * The number of insert strings in the array pointed to by the 1463 * lpStrings parameter. A value of zero indicates that no strings 1464 * are present. 1465 * @param dwDataSize 1466 * The number of bytes of event-specific raw (binary) data to 1467 * write to the log. If this parameter is zero, no event-specific 1468 * data is present. 1469 * @param lpStrings 1470 * A pointer to a buffer containing an array of null-terminated 1471 * strings that are merged into the message before Event Viewer 1472 * displays the string to the user. This parameter must be a 1473 * valid pointer (or NULL), even if wNumStrings is zero. Each 1474 * string is limited to 31,839 characters. 1475 * @param lpRawData 1476 * A pointer to the buffer containing the binary data. This 1477 * parameter must be a valid pointer (or NULL), even if the 1478 * dwDataSize parameter is zero. 1479 * @return If the function succeeds, the return value is nonzero, indicating 1480 * that the entry was written to the log. If the function fails, the 1481 * return value is zero. To get extended error information, call 1482 * GetLastError. 1483 */ ReportEvent(HANDLE hEventLog, int wType, int wCategory, int dwEventID, PSID lpUserSid, int wNumStrings, int dwDataSize, String[] lpStrings, Pointer lpRawData)1484 boolean ReportEvent(HANDLE hEventLog, int wType, int wCategory, 1485 int dwEventID, PSID lpUserSid, int wNumStrings, int dwDataSize, 1486 String[] lpStrings, Pointer lpRawData); 1487 1488 /** 1489 * Clears the specified event log, and optionally saves the current copy of 1490 * the log to a backup file. 1491 * 1492 * @param hEventLog 1493 * A handle to the event log to be cleared. The OpenEventLog 1494 * function returns this handle. 1495 * @param lpBackupFileName 1496 * The absolute or relative path of the backup file. If this file 1497 * already exists, the function fails. If the lpBackupFileName 1498 * parameter is NULL, the event log is not backed up. 1499 * @return If the function succeeds, the return value is nonzero. If the 1500 * function fails, the return value is zero. To get extended error 1501 * information, call GetLastError. The ClearEventLog function can 1502 * fail if the event log is empty or the backup file already exists. 1503 */ ClearEventLog(HANDLE hEventLog, String lpBackupFileName)1504 boolean ClearEventLog(HANDLE hEventLog, String lpBackupFileName); 1505 1506 /** 1507 * Saves the specified event log to a backup file. The function does not 1508 * clear the event log. 1509 * 1510 * @param hEventLog 1511 * A handle to the open event log. The OpenEventLog function 1512 * returns this handle. 1513 * @param lpBackupFileName 1514 * The absolute or relative path of the backup file. 1515 * @return If the function succeeds, the return value is nonzero. If the 1516 * function fails, the return value is zero. To get extended error 1517 * information, call GetLastError. 1518 */ BackupEventLog(HANDLE hEventLog, String lpBackupFileName)1519 boolean BackupEventLog(HANDLE hEventLog, String lpBackupFileName); 1520 1521 /** 1522 * Opens a handle to a backup event log created by the BackupEventLog 1523 * function. 1524 * 1525 * @param lpUNCServerName 1526 * The Universal Naming Convention (UNC) name of the remote 1527 * server on which this operation is to be performed. If this 1528 * parameter is NULL, the local computer is used. 1529 * @param lpFileName 1530 * The full path of the backup file. 1531 * @return If the function succeeds, the return value is a handle to the 1532 * backup event log. If the function fails, the return value is 1533 * NULL. To get extended error information, call GetLastError. 1534 */ OpenBackupEventLog(String lpUNCServerName, String lpFileName)1535 HANDLE OpenBackupEventLog(String lpUNCServerName, String lpFileName); 1536 1537 /** 1538 * Reads the specified number of entries from the specified event log. The 1539 * function can be used to read log entries in chronological or reverse 1540 * chronological order. 1541 * 1542 * @param hEventLog 1543 * A handle to the event log to be read. The OpenEventLog 1544 * function returns this handle. 1545 * @param dwReadFlags 1546 * Use the following flag values to indicate how to read the log 1547 * file. 1548 * @param dwRecordOffset 1549 * The record number of the log-entry at which the read operation 1550 * should start. This parameter is ignored unless dwReadFlags 1551 * includes the EVENTLOG_SEEK_READ flag. 1552 * @param lpBuffer 1553 * An application-allocated buffer that will receive one or more 1554 * EVENTLOGRECORD structures. This parameter cannot be NULL, even 1555 * if the nNumberOfBytesToRead parameter is zero. The maximum 1556 * size of this buffer is 0x7ffff bytes. 1557 * @param nNumberOfBytesToRead 1558 * The size of the lpBuffer buffer, in bytes. This function will 1559 * read as many log entries as will fit in the buffer; the 1560 * function will not return partial entries. 1561 * @param pnBytesRead 1562 * A pointer to a variable that receives the number of bytes read 1563 * by the function. 1564 * @param pnMinNumberOfBytesNeeded 1565 * A pointer to a variable that receives the required size of the 1566 * lpBuffer buffer. This value is valid only this function 1567 * returns zero and GetLastError returns 1568 * ERROR_INSUFFICIENT_BUFFER. 1569 * @return If the function succeeds, the return value is nonzero. If the 1570 * function fails, the return value is zero. To get extended error 1571 * information, call GetLastError. 1572 */ ReadEventLog(HANDLE hEventLog, int dwReadFlags, int dwRecordOffset, Pointer lpBuffer, int nNumberOfBytesToRead, IntByReference pnBytesRead, IntByReference pnMinNumberOfBytesNeeded)1573 boolean ReadEventLog(HANDLE hEventLog, int dwReadFlags, 1574 int dwRecordOffset, Pointer lpBuffer, int nNumberOfBytesToRead, 1575 IntByReference pnBytesRead, IntByReference pnMinNumberOfBytesNeeded); 1576 1577 /** 1578 * The GetOldestEventLogRecord function retrieves the absolute record number 1579 * of the oldest record in the specified event log. 1580 * 1581 * @param hEventLog 1582 * Handle to the open event log. This handle is returned by the 1583 * OpenEventLog or OpenBackupEventLog function. 1584 * @param OldestRecord 1585 * Pointer to a variable that receives the absolute record number 1586 * of the oldest record in the specified event log. 1587 * @return If the function succeeds, the return value is nonzero. If the 1588 * function fails, the return value is zero. To get extended error 1589 * information, call GetLastError. 1590 */ GetOldestEventLogRecord(HANDLE hEventLog, IntByReference OldestRecord)1591 boolean GetOldestEventLogRecord(HANDLE hEventLog, IntByReference OldestRecord); 1592 1593 /** 1594 * Changes the optional configuration parameters of a service. 1595 * 1596 * @param hService 1597 * A handle to the service. This handle is returned by the 1598 * OpenService or CreateService function and must have the 1599 * SERVICE_CHANGE_CONFIG access right. For more information, 1600 * see <a 1601 * href="http://msdn.microsoft.com/en-us/library/ms685981.aspx" 1602 * >Service Security and Access Rights</a>. 1603 * If the service controller handles the SC_ACTION_RESTART 1604 * action, hService must have the SERVICE_START access right. 1605 * @param dwInfoLevel 1606 * The configuration information to be changed. 1607 * @param lpInfo 1608 * A pointer to the new value to be set for the configuration 1609 * information. The format of this data depends on the value 1610 * of the dwInfoLevel parameter. If this value is NULL, the 1611 * information remains unchanged. 1612 * @return If the function succeeds, the return value is nonzero. 1613 * If the function fails, the return value is zero. To get extended 1614 * error information, call GetLastError. 1615 */ ChangeServiceConfig2(SC_HANDLE hService, int dwInfoLevel, ChangeServiceConfig2Info lpInfo)1616 public boolean ChangeServiceConfig2(SC_HANDLE hService, int dwInfoLevel, 1617 ChangeServiceConfig2Info lpInfo); 1618 1619 /** 1620 * Retrieves the optional configuration parameters of the specified service. 1621 * 1622 * @param hService 1623 * A handle to the service. This handle is returned by the OpenService or 1624 * CreateService function and must have the SERVICE_QUERY_CONFIG access right. For 1625 * more information, see Service Security and Access Rights. 1626 * @param dwInfoLevel 1627 * The configuration information to be queried. 1628 * @param lpBuffer 1629 * A pointer to the buffer that receives the service configuration information. The 1630 * format of this data depends on the value of the dwInfoLevel parameter. 1631 * The maximum size of this array is 8K bytes. To determine the required size, 1632 * specify NULL for this parameter and 0 for the cbBufSize parameter. The function 1633 * fails and GetLastError returns ERROR_INSUFFICIENT_BUFFER. The pcbBytesNeeded 1634 * parameter receives the needed size. 1635 * @param cbBufSize 1636 * The size of the structure pointed to by the lpBuffer parameter, in bytes. 1637 * @param pcbBytesNeeded 1638 * A pointer to a variable that receives the number of bytes required to store the 1639 * configuration information, if the function fails with ERROR_INSUFFICIENT_BUFFER. 1640 * @return If the function succeeds, the return value is nonzero. 1641 * If the function fails, the return value is zero. To get extended error information, 1642 * call GetLastError. 1643 */ QueryServiceConfig2(SC_HANDLE hService, int dwInfoLevel, Pointer lpBuffer, int cbBufSize, IntByReference pcbBytesNeeded)1644 public boolean QueryServiceConfig2(SC_HANDLE hService, int dwInfoLevel, 1645 Pointer lpBuffer, int cbBufSize, IntByReference pcbBytesNeeded); 1646 1647 1648 /** 1649 * Retrieves the current status of the specified service based on the 1650 * specified information level. 1651 * 1652 * @param hService 1653 * A handle to the service. This handle is returned by the 1654 * OpenService(SC_HANDLE, String, int) or CreateService() 1655 * function, and it must have the SERVICE_QUERY_STATUS access 1656 * right. For more information, see <a 1657 * href="http://msdn.microsoft.com/en-us/library/ms685981.aspx" 1658 * >Service Security and Access Rights</a>. 1659 * @param InfoLevel 1660 * The service attributes to be returned (a value from 1661 * SC_STATUS_TYPE enumeration). Use SC_STATUS_PROCESS_INFO to 1662 * retrieve the service status information. The lpBuffer 1663 * parameter is a pointer to a SERVICE_STATUS_PROCESS structure. 1664 * Currently, no other information levels are defined. 1665 * @param lpBuffer 1666 * (optional) A pointer to the buffer that receives the status 1667 * information. The format of this data depends on the value of 1668 * the InfoLevel parameter. The maximum size of this array is 8K 1669 * bytes. To determine the required size, specify NULL for this 1670 * parameter and 0 for the cbBufSize parameter. The function will 1671 * fail and GetLastError will return ERROR_INSUFFICIENT_BUFFER. 1672 * The pcbBytesNeeded parameter will receive the required size. 1673 * @param cbBufSize 1674 * The size of the buffer pointed to by the lpBuffer parameter, 1675 * in bytes. 1676 * @param pcbBytesNeeded 1677 * A pointer to a variable that receives the number of bytes 1678 * needed to store all status information, if the function fails 1679 * with ERROR_INSUFFICIENT_BUFFER. 1680 * @return If the function succeeds, the return value is true. If the 1681 * function fails, the return value is false. To get extended error 1682 * information, call GetLastError. This value is a nonzero error 1683 * code defined in Winerror.h. 1684 */ QueryServiceStatusEx(SC_HANDLE hService, int InfoLevel, SERVICE_STATUS_PROCESS lpBuffer, int cbBufSize, IntByReference pcbBytesNeeded)1685 boolean QueryServiceStatusEx(SC_HANDLE hService, int InfoLevel, 1686 SERVICE_STATUS_PROCESS lpBuffer, int cbBufSize, 1687 IntByReference pcbBytesNeeded); 1688 1689 /** 1690 * Retrieves the current status of the specified service based on the 1691 * specified information level. 1692 * 1693 * @param hService 1694 * A handle to the service. This handle is returned by the 1695 * OpenService(SC_HANDLE, String, int) or CreateService() 1696 * function, and it must have the SERVICE_QUERY_STATUS access 1697 * right. For more information, see <a 1698 * href="http://msdn.microsoft.com/en-us/library/ms685981.aspx" 1699 * >Service Security and Access Rights</a>. 1700 * @param lpServiceStatus 1701 * A pointer to a SERVICE_STATUS structure that receives the status information. 1702 * @return If the function succeeds, the return value is true. If the 1703 * function fails, the return value is false. To get extended error 1704 * information, call GetLastError. 1705 */ QueryServiceStatus(SC_HANDLE hService, SERVICE_STATUS lpServiceStatus)1706 boolean QueryServiceStatus(SC_HANDLE hService, SERVICE_STATUS lpServiceStatus); 1707 1708 /** 1709 * Sends a control code to a service. To specify additional information when 1710 * stopping a service, use the ControlServiceEx function. 1711 * 1712 * @param hService 1713 * A handle to the service. This handle is returned by the 1714 * OpenService(SC_HANDLE, String, int) or CreateService() 1715 * function. The access rights required for this handle depend on 1716 * the dwControl code requested. 1717 * @param dwControl 1718 * This parameter can be one of the following control codes 1719 * (found in Winsvc.h): SERVICE_CONTROL_STOP, 1720 * SERVICE_CONTROL_PAUSE, SERVICE_CONTROL_CONTINUE 1721 * SERVICE_CONTROL_INTERROGATE, SERVICE_CONTROL_PARAMCHANGE, 1722 * SERVICE_CONTROL_NETBINDADD, SERVICE_CONTROL_NETBINDREMOVE, 1723 * SERVICE_CONTROL_NETBINDENABLE, SERVICE_CONTROL_NETBINDDISABLE 1724 * This value can also be a user-defined control code, as 1725 * described below: Range 128 to 255 - The service defines the 1726 * action associated with the control code. The hService handle 1727 * must have the SERVICE_USER_DEFINED_CONTROL access right. 1728 * @param lpServiceStatus 1729 * A pointer to a SERVICE_STATUS structure that receives the 1730 * latest service status information. The information returned 1731 * reflects the most recent status that the service reported to 1732 * the service control manager. The service control manager fills 1733 * in the structure only when ControlService returns one of the 1734 * following error codes: NO_ERROR, 1735 * ERROR_INVALID_SERVICE_CONTROL, 1736 * ERROR_SERVICE_CANNOT_ACCEPT_CTRL, or ERROR_SERVICE_NOT_ACTIVE. 1737 * Otherwise, the structure is not filled in. 1738 * @return If the function succeeds, the return value is true. If the 1739 * function fails, the return value is false. To get extended error 1740 * information, call GetLastError. This value is a nonzero error 1741 * code defined in Winerror.h. 1742 */ ControlService(SC_HANDLE hService, int dwControl, SERVICE_STATUS lpServiceStatus)1743 boolean ControlService(SC_HANDLE hService, int dwControl, SERVICE_STATUS lpServiceStatus); 1744 1745 /** 1746 * Starts a service. 1747 * 1748 * @param hService 1749 * A handle to the service. This handle is returned by the 1750 * OpenService(SC_HANDLE, String, int) or CreateService() 1751 * function, and it must have the SERVICE_START access right. For 1752 * more information, see <a 1753 * href="http://msdn.microsoft.com/en-us/library/ms685981.aspx"> 1754 * Service Security and Access Rights</a>. 1755 * @param dwNumServiceArgs 1756 * The number of strings in the lpServiceArgVectors array. If 1757 * lpServiceArgVectors is NULL, this parameter can be zero. 1758 * @param lpServiceArgVectors 1759 * The null-terminated strings to be passed to the ServiceMain 1760 * function for the service as arguments. If there are no 1761 * arguments, this parameter can be null. Otherwise, the first 1762 * argument (lpServiceArgVectors[0]) is the name of the service, 1763 * followed by any additional arguments (lpServiceArgVectors[1] 1764 * through lpServiceArgVectors[dwNumServiceArgs-1]). Driver 1765 * services do not receive these arguments. 1766 * @return If the function succeeds, the return value is true. If the 1767 * function fails, the return value is false. To get extended error 1768 * information, call GetLastError. This value is a nonzero error 1769 * code defined in Winerror.h. 1770 */ StartService(SC_HANDLE hService, int dwNumServiceArgs, String[] lpServiceArgVectors)1771 boolean StartService(SC_HANDLE hService, int dwNumServiceArgs, String[] lpServiceArgVectors); 1772 1773 /** 1774 * Closes a handle to a service control manager or service object. 1775 * 1776 * @param hSCObject 1777 * A handle to the service control manager object or the service 1778 * object to close. Handles to service control manager objects 1779 * are returned by the OpenSCManager(String, String, int) 1780 * function, and handles to service objects are returned by 1781 * either the OpenService(SC_HANDLE, String, int) or 1782 * CreateService() function. 1783 * @return If the function succeeds, the return value is nonzero. If the 1784 * function fails, the return value is zero. To get extended error 1785 * information, call GetLastError. This value is a nonzero error 1786 * code defined in Winerror.h. 1787 */ CloseServiceHandle(SC_HANDLE hSCObject)1788 boolean CloseServiceHandle(SC_HANDLE hSCObject); 1789 1790 /** 1791 * Opens an existing service. 1792 * 1793 * @param hSCManager 1794 * A handle to the service control manager database. The 1795 * OpenSCManager(String, String, int) function returns this 1796 * handle. 1797 * @param lpServiceName 1798 * The name of the service to be opened. This is the name 1799 * specified by the lpServiceName parameter of the CreateService 1800 * function when the service object was created, not the service 1801 * display name that is shown by user interface applications to 1802 * identify the service. The maximum string length is 256 1803 * characters. The service control manager database preserves the 1804 * case of the characters, but service name comparisons are 1805 * always case insensitive. Forward-slash (/) and backslash (\) 1806 * are invalid service name characters. 1807 * @param dwDesiredAccess 1808 * The access to the service. For a list of access rights, see <a 1809 * href="http://msdn.microsoft.com/en-us/library/ms685981.aspx"> 1810 * Service Security and Access Rights</a>. Before granting the 1811 * requested access, the system checks the access token of the 1812 * calling process against the discretionary access-control list 1813 * of the security descriptor associated with the service object. 1814 * @return If the function succeeds, the return value is a handle to the 1815 * service. If the function fails, the return value is NULL. To get 1816 * extended error information, call GetLastError. This value is a 1817 * nonzero error code defined in Winerror.h. 1818 */ OpenService(SC_HANDLE hSCManager, String lpServiceName, int dwDesiredAccess)1819 SC_HANDLE OpenService(SC_HANDLE hSCManager, String lpServiceName, int dwDesiredAccess); 1820 1821 /** 1822 * Establishes a connection to the service control manager on the specified 1823 * computer and opens the specified service control manager database. 1824 * 1825 * @param lpMachineName 1826 * The name of the target computer. If the pointer is NULL or 1827 * points to an empty string, the function connects to the 1828 * service control manager on the local computer. 1829 * @param lpDatabaseName 1830 * The name of the service control manager database. This 1831 * parameter should be set to SERVICES_ACTIVE_DATABASE. If it is 1832 * NULL, the SERVICES_ACTIVE_DATABASE database is opened by 1833 * default. 1834 * @param dwDesiredAccess 1835 * The access to the service control manager. For a list of 1836 * access rights, see <a 1837 * href="http://msdn.microsoft.com/en-us/library/ms685981.aspx"> 1838 * Service Security and Access Rights</a>. Before granting the 1839 * requested access rights, the system checks the access token of 1840 * the calling process against the discretionary access-control 1841 * list of the security descriptor associated with the service 1842 * control manager. The SC_MANAGER_CONNECT access right is 1843 * implicitly specified by calling this function. 1844 * @return If the function succeeds, the return value is a handle to the 1845 * specified service control manager database. If the function 1846 * fails, the return value is NULL. To get extended error 1847 * information, call GetLastError. This value is a nonzero error 1848 * code defined in Winerror.h. 1849 */ OpenSCManager(String lpMachineName, String lpDatabaseName, int dwDesiredAccess)1850 SC_HANDLE OpenSCManager(String lpMachineName, String lpDatabaseName, int dwDesiredAccess); 1851 1852 /** 1853 * Retrieves the name and status of each service that depends on the 1854 * specified service; that is, the specified service must be running before 1855 * the dependent services can run. 1856 * 1857 * @param hService A handle to the service. This handle is 1858 * returned by the OpenService or CreateService 1859 * function, and it must have the 1860 * SERVICE_ENUMERATE_DEPENDENTS access right. For 1861 * more information, see Service Security and 1862 * Access Rights. 1863 * @param dwServiceState The state of the services to be enumerated. 1864 * This parameter can be one of the following 1865 * values. 1866 * <table> 1867 * <tr><th>Value</th><th>Meaning</th></tr> 1868 * <tr><td>{@link Winsvc#SERVICE_ACTIVE}</td><td>Enumerates services that 1869 * are in the following states: 1870 * {@link Winsvc#SERVICE_START_PENDING}, {@link Winsvc#SERVICE_STOP_PENDING}, {@link Winsvc#SERVICE_RUNNING}, {@link Winsvc#SERVICE_CONTINUE_PENDING}, {@link Winsvc#SERVICE_PAUSE_PENDING}, 1871 * and {@link Winsvc#SERVICE_PAUSED}.</td></tr> 1872 * <tr><td>{@link Winsvc#SERVICE_INACTIVE}</td><td>Enumerates services that 1873 * are in the {@link Winsvc#SERVICE_STOPPED} state.</td></tr> 1874 * <tr><td>{@link Winsvc#SERVICE_STATE_ALL}</td><td>Combines the following 1875 * states: {@link Winsvc#SERVICE_ACTIVE} and 1876 * {@link Winsvc#SERVICE_INACTIVE}.</td></tr> 1877 * </table> 1878 * @param lpService A pointer to an array of ENUM_SERVICE_STATUS 1879 * structures that receives the name and service 1880 * status information for each dependent service 1881 * in the database. The buffer must be large 1882 * enough to hold the structures, plus the strings 1883 * to which their members point. 1884 * <p> 1885 * The order of the services in this array is the reverse of the start order 1886 * of the services. In other words, the first service in the array is the 1887 * one that would be started last, and the last service in the array is the 1888 * one that would be started first.</p> 1889 * <p> 1890 * The maximum size of this array is 64,000 bytes. To determine the required 1891 * size, specify NULL for this parameter and 0 for the cbBufSize parameter. 1892 * The function will fail and GetLastError will return ERROR_MORE_DATA. The 1893 * pcbBytesNeeded parameter will receive the required size.</p> 1894 * @param cbBufSize The size of the buffer pointed to by the 1895 * lpServices parameter, in bytes. 1896 * @param pcbBytesNeeded A pointer to a variable that receives the 1897 * number of bytes needed to store the array of 1898 * service entries. The variable only receives 1899 * this value if the buffer pointed to by 1900 * lpServices is too small, indicated by function 1901 * failure and the ERROR_MORE_DATA error; 1902 * otherwise, the contents of pcbBytesNeeded are 1903 * undefined. 1904 * @param lpServicesReturned A pointer to a variable that receives the 1905 * number of service entries returned. 1906 * 1907 * @return If the function succeeds, the return value is nonzero. 1908 * 1909 * <p>If the function fails, the return value is zero. To get extended error 1910 * information, call GetLastError.</p> 1911 * 1912 * <p>The following error codes may be set by the service control manager. 1913 * Other error codes may be set by the registry functions that are called by 1914 * the service control manager.</p> 1915 * 1916 * <table> 1917 * <tr><th>Return code</th><th>Description</th></tr> 1918 * <tr><td>{@link WinError#ERROR_ACCESS_DENIED}</td><td>The handle does not have the {@link Winsvc#SERVICE_ENUMERATE_DEPENDENTS} access right.</td></tr> 1919 * <tr><td>{@link WinError#ERROR_INVALID_HANDLE}</td><td>The specified handle is invalid.</td></tr> 1920 * <tr><td>{@link WinError#ERROR_INVALID_PARAMETER}</td><td>A parameter that was specified is invalid.</td></tr> 1921 * <tr><td>{@link WinError#ERROR_MORE_DATA}</td><td>The buffer pointed to by lpServices is not large enough. The function sets the variable pointed to by lpServicesReturned to the actual number of service entries stored into the buffer. The function sets the variable pointed to by pcbBytesNeeded to the number of bytes required to store all of the service entries.</td></tr> 1922 * </table> 1923 */ EnumDependentServices(SC_HANDLE hService, int dwServiceState, Pointer lpService, int cbBufSize, IntByReference pcbBytesNeeded, IntByReference lpServicesReturned)1924 boolean EnumDependentServices(SC_HANDLE hService, int dwServiceState, 1925 Pointer lpService, int cbBufSize, IntByReference pcbBytesNeeded, 1926 IntByReference lpServicesReturned); 1927 1928 /** 1929 * Enumerates services in the specified service control manager database. 1930 * The name and status of each service are provided, along with additional 1931 * data based on the specified information level. 1932 * 1933 * @param hSCManager A handle to the service control manager 1934 * database. This handle is returned by the 1935 * {@link #OpenSCManager} function, and must have 1936 * the {@link Winsvc#SC_MANAGER_ENUMERATE_SERVICE} 1937 * access right. For more information, see Service 1938 * Security and Access Rights. 1939 * @param InfoLevel The service attributes that are to be returned. 1940 * Use {@link Winsvc#SC_ENUM_PROCESS_INFO} to 1941 * retrieve the name and service status 1942 * information for each service in the database. 1943 * The lpServices parameter is a pointer to a 1944 * buffer that receives an array of 1945 * {@link Winsvc.ENUM_SERVICE_STATUS_PROCESS} 1946 * structures. The buffer must be large enough to 1947 * hold the structures as well as the strings to 1948 * which their members point. 1949 * 1950 * <p>Currently, no other information levels are defined.</p> 1951 * @param dwServiceType The type of services to be enumerated. This 1952 * parameter can be one or more of the following 1953 * values. 1954 * 1955 * <table> 1956 * <tr><th>Value</th><th>Meaning</th></tr> 1957 * <tr><td>{@link WinNT#SERVICE_DRIVER}</td><td>Services of type {@link WinNT#SERVICE_KERNEL_DRIVER} and {@link WinNT#SERVICE_FILE_SYSTEM_DRIVER}.</td></tr> 1958 * <tr><td>{@link WinNT#SERVICE_FILE_SYSTEM_DRIVER}</td><td>File system driver services.</td></tr> 1959 * <tr><td>{@link WinNT#SERVICE_KERNEL_DRIVER}</td><td>Driver services.</td></tr> 1960 * <tr><td>{@link WinNT#SERVICE_WIN32}</td><td>Services of type {@link WinNT#SERVICE_WIN32_OWN_PROCESS} and {@link WinNT#SERVICE_WIN32_SHARE_PROCESS}.</td></tr> 1961 * <tr><td>{@link WinNT#SERVICE_WIN32_OWN_PROCESS}</td><td>Services that run in their own processes.</td></tr> 1962 * <tr><td>{@link WinNT#SERVICE_WIN32_SHARE_PROCESS}</td><td>Services that share a process with one or more other services. For more information, see Service Programs.</td></tr> 1963 * </table> 1964 * 1965 * @param dwServiceState The state of the services to be enumerated. 1966 * This parameter can be one of the following 1967 * values. 1968 * <table> 1969 * <tr><th>Value</th><th>Meaning</th></tr> 1970 * <tr><td>{@link Winsvc#SERVICE_ACTIVE}</td><td>Enumerates services that 1971 * are in the following states: 1972 * {@link Winsvc#SERVICE_START_PENDING}, {@link Winsvc#SERVICE_STOP_PENDING}, {@link Winsvc#SERVICE_RUNNING}, {@link Winsvc#SERVICE_CONTINUE_PENDING}, {@link Winsvc#SERVICE_PAUSE_PENDING}, 1973 * and {@link Winsvc#SERVICE_PAUSED}.</td></tr> 1974 * <tr><td>{@link Winsvc#SERVICE_INACTIVE}</td><td>Enumerates services that 1975 * are in the {@link Winsvc#SERVICE_STOPPED} state.</td></tr> 1976 * <tr><td>{@link Winsvc#SERVICE_STATE_ALL}</td><td>Combines the following 1977 * states: {@link Winsvc#SERVICE_ACTIVE} and 1978 * {@link Winsvc#SERVICE_INACTIVE}.</td></tr> 1979 * </table> 1980 * @param lpServices A pointer to the buffer that receives the 1981 * status information. The format of this data 1982 * depends on the value of the InfoLevel 1983 * parameter. 1984 * 1985 * <p>The maximum size of this array is 256K bytes. To determine the required 1986 * size, specify NULL for this parameter and 0 for the cbBufSize parameter. 1987 * The function will fail and GetLastError will return ERROR_MORE_DATA. The 1988 * pcbBytesNeeded parameter will receive the required size.</p> 1989 * 1990 * <p><b>Windows Server 2003 and Windows XP:</b> The maximum size of this array is 64K 1991 * bytes. This limit was increased as of Windows Server 2003 with SP1 and 1992 * Windows XP with SP2.</p> 1993 1994 * @param cbBufSize The size of the buffer pointed to by the 1995 * lpServices parameter, in bytes. 1996 * @param pcbBytesNeeded A pointer to a variable that receives the 1997 * number of bytes needed to store the array of 1998 * service entries. The variable only receives 1999 * this value if the buffer pointed to by 2000 * lpServices is too small, indicated by function 2001 * failure and the ERROR_MORE_DATA error; 2002 * otherwise, the contents of pcbBytesNeeded are 2003 * undefined. 2004 * @param lpServicesReturned A pointer to a variable that receives the 2005 * number of service entries returned. 2006 * @param lpResumeHandle A pointer to a variable that, on input, 2007 * specifies the starting point of enumeration. 2008 * You must set this value to zero the first time 2009 * the {@link #EnumServicesStatusEx} function is 2010 * called. On output, this value is zero if the 2011 * function succeeds. However, if the function 2012 * returns zero and the 2013 * {@link Kernel32#GetLastError} function returns 2014 * {@link WinError#ERROR_MORE_DATA}, this value 2015 * indicates the next service entry to be read 2016 * when the {@link #EnumServicesStatusEx} function 2017 * is called to retrieve the additional data. 2018 * @param pszGroupName The load-order group name. If this parameter is 2019 * a string, the only services enumerated are 2020 * those that belong to the group that has the 2021 * name specified by the string. If this parameter 2022 * is an empty string, only services that do not 2023 * belong to any group are enumerated. If this 2024 * parameter is NULL, group membership is ignored 2025 * and all services are enumerated. 2026 * 2027 * @return If the function succeeds, the return value is nonzero. 2028 * 2029 * <p> 2030 * If the function succeeds, the return value is nonzero.</p> 2031 * <p> 2032 * If the function fails, the return value is zero. To get extended error 2033 * information, call GetLastError. The following errors may be returned.</p> 2034 * 2035 * <table> 2036 * <tr><th>Return code</th><th>Description</th></tr> 2037 * <tr><td>{@link WinError#ERROR_ACCESS_DENIED}</td><td>The handle does not have the {@link Winsvc#SERVICE_ENUMERATE_DEPENDENTS} access right.</td></tr> 2038 * <tr><td>{@link WinError#ERROR_MORE_DATA}</td><td>The buffer pointed to by lpServices is not large enough. The function sets the variable pointed to by lpServicesReturned to the actual number of service entries stored into the buffer. The function sets the variable pointed to by pcbBytesNeeded to the number of bytes required to store all of the service entries.</td></tr> 2039 * <tr><td>{@link WinError#ERROR_INVALID_HANDLE}</td><td>The specified handle is invalid.</td></tr> 2040 * <tr><td>{@link WinError#ERROR_INVALID_PARAMETER}</td><td>A parameter that was specified is invalid.</td></tr> 2041 * <tr><td>{@link WinError#ERROR_INVALID_LEVEL}</td><td>The InfoLevel parameter contains an unsupported value.</td></tr> 2042 * <tr><td>{@link WinError#ERROR_SHUTDOWN_IN_PROGRESS}</td><td>The system is shutting down; this function cannot be called.</td></tr> 2043 * </table> 2044 */ EnumServicesStatusEx(SC_HANDLE hSCManager, int InfoLevel, int dwServiceType, int dwServiceState, Pointer lpServices, int cbBufSize, IntByReference pcbBytesNeeded, IntByReference lpServicesReturned, IntByReference lpResumeHandle, String pszGroupName)2045 boolean EnumServicesStatusEx(SC_HANDLE hSCManager, int InfoLevel, 2046 int dwServiceType, int dwServiceState, Pointer lpServices, 2047 int cbBufSize, IntByReference pcbBytesNeeded, 2048 IntByReference lpServicesReturned, IntByReference lpResumeHandle, 2049 String pszGroupName); 2050 2051 /** 2052 * Creates a new process and its primary thread. The new process runs in the 2053 * security context of the user represented by the specified token. 2054 * 2055 * Typically, the process that calls the CreateProcessAsUser function must 2056 * have the SE_INCREASE_QUOTA_NAME privilege and may require the 2057 * SE_ASSIGNPRIMARYTOKEN_NAME privilege if the token is not assignable. If 2058 * this function fails with ERROR_PRIVILEGE_NOT_HELD (1314), use the 2059 * CreateProcessWithLogonW function instead. CreateProcessWithLogonW 2060 * requires no special privileges, but the specified user account must be 2061 * allowed to log on interactively. Generally, it is best to use 2062 * CreateProcessWithLogonW to create a process with alternate credentials. 2063 * 2064 * @param hToken 2065 * A handle to the primary token that represents a user. 2066 * @param lpApplicationName 2067 * The name of the module to be executed. 2068 * @param lpCommandLine 2069 * The command line to be executed. 2070 * @param lpProcessAttributes 2071 * A pointer to a SECURITY_ATTRIBUTES structure that specifies a 2072 * security descriptor for the new process object and determines 2073 * whether child processes can inherit the returned handle to the 2074 * process. 2075 * @param lpThreadAttributes 2076 * A pointer to a SECURITY_ATTRIBUTES structure that specifies a 2077 * security descriptor for the new thread object and determines 2078 * whether child processes can inherit the returned handle to the 2079 * thread. 2080 * @param bInheritHandles 2081 * If this parameter is TRUE, each inheritable handle in the 2082 * calling process is inherited by the new process. If the 2083 * parameter is FALSE, the handles are not inherited. Note that 2084 * inherited handles have the same value and access rights as the 2085 * original handles. 2086 * @param dwCreationFlags 2087 * The flags that control the priority class and the creation of 2088 * the process. For a list of values, see Process Creation Flags. 2089 * @param lpEnvironment 2090 * A pointer to an environment block for the new process. If this 2091 * parameter is NULL, the new process uses the environment of the 2092 * calling process. 2093 * 2094 * An environment block consists of a null-terminated block of 2095 * null-terminated strings. Each string is in the following form: 2096 * name=value\0 2097 * @param lpCurrentDirectory 2098 * The full path to the current directory for the process. The 2099 * string can also specify a UNC path. 2100 * @param lpStartupInfo 2101 * A pointer to a STARTUPINFO or STARTUPINFOEX structure. 2102 * @param lpProcessInformation 2103 * A pointer to a PROCESS_INFORMATION structure that receives 2104 * identification information about the new process. 2105 * @return If the function succeeds, the return value is nonzero. If the 2106 * function fails, the return value is zero. To get extended error 2107 * information, call GetLastError. 2108 */ CreateProcessAsUser(HANDLE hToken, String lpApplicationName, String lpCommandLine, SECURITY_ATTRIBUTES lpProcessAttributes, SECURITY_ATTRIBUTES lpThreadAttributes, boolean bInheritHandles, int dwCreationFlags, String lpEnvironment, String lpCurrentDirectory, WinBase.STARTUPINFO lpStartupInfo, WinBase.PROCESS_INFORMATION lpProcessInformation)2109 boolean CreateProcessAsUser(HANDLE hToken, String lpApplicationName, 2110 String lpCommandLine, SECURITY_ATTRIBUTES lpProcessAttributes, 2111 SECURITY_ATTRIBUTES lpThreadAttributes, boolean bInheritHandles, 2112 int dwCreationFlags, String lpEnvironment, 2113 String lpCurrentDirectory, WinBase.STARTUPINFO lpStartupInfo, 2114 WinBase.PROCESS_INFORMATION lpProcessInformation); 2115 2116 /** 2117 * The AdjustTokenPrivileges function enables or disables privileges in the 2118 * specified access token. Enabling or disabling privileges in an access 2119 * token requires TOKEN_ADJUST_PRIVILEGES access. 2120 * 2121 * @param TokenHandle 2122 * A handle to the access token that contains the privileges to 2123 * be modified. 2124 * @param DisableAllPrivileges 2125 * Specifies whether the function disables all of the token's 2126 * privileges. 2127 * @param NewState 2128 * A pointer to a TOKEN_PRIVILEGES structure that specifies an 2129 * array of privileges and their attributes. 2130 * @param BufferLength 2131 * Specifies the size, in bytes, of the buffer pointed to by the 2132 * PreviousState parameter. This parameter can be zero if the 2133 * PreviousState parameter is NULL. 2134 * @param PreviousState 2135 * A pointer to a buffer that the function fills with a 2136 * TOKEN_PRIVILEGES structure that contains the previous state of 2137 * any privileges that the function modifies. 2138 * @param ReturnLength 2139 * A pointer to a variable that receives the required size, in 2140 * bytes, of the buffer pointed to by the PreviousState 2141 * parameter. 2142 * @return If the function succeeds, the return value is nonzero. If the 2143 * function fails, the return value is zero. To get extended error 2144 * information, call GetLastError. 2145 */ AdjustTokenPrivileges(HANDLE TokenHandle, boolean DisableAllPrivileges, WinNT.TOKEN_PRIVILEGES NewState, int BufferLength, WinNT.TOKEN_PRIVILEGES PreviousState, IntByReference ReturnLength)2146 boolean AdjustTokenPrivileges(HANDLE TokenHandle, 2147 boolean DisableAllPrivileges, WinNT.TOKEN_PRIVILEGES NewState, 2148 int BufferLength, WinNT.TOKEN_PRIVILEGES PreviousState, 2149 IntByReference ReturnLength); 2150 2151 /** 2152 * The LookupPrivilegeName function retrieves the name that corresponds to 2153 * the privilege represented on a specific system by a specified locally 2154 * unique identifier (LUID). 2155 * 2156 * @param lpSystemName 2157 * A pointer to a null-terminated string that specifies the name 2158 * of the system on which the privilege name is retrieved. If a 2159 * null string is specified, the function attempts to find the 2160 * privilege name on the local system. 2161 * @param lpLuid 2162 * A pointer to the LUID by which the privilege is known on the 2163 * target system. 2164 * @param lpName 2165 * A pointer to a buffer that receives a null-terminated string 2166 * that represents the privilege name. For example, this string 2167 * could be "SeSecurityPrivilege". 2168 * @param cchName 2169 * A pointer to a variable that specifies the size, in a TCHAR 2170 * value, of the lpName buffer. 2171 * @return If the function succeeds, the return value is nonzero. If the 2172 * function fails, the return value is zero. To get extended error 2173 * information, call GetLastError. 2174 */ LookupPrivilegeName(String lpSystemName, WinNT.LUID lpLuid, char[] lpName, IntByReference cchName)2175 boolean LookupPrivilegeName(String lpSystemName, WinNT.LUID lpLuid, 2176 char[] lpName, IntByReference cchName); 2177 2178 /** 2179 * The LookupPrivilegeValue function retrieves the locally unique identifier 2180 * (LUID) used on a specified system to locally represent the specified 2181 * privilege name. 2182 * 2183 * @param lpSystemName 2184 * A pointer to a null-terminated string that specifies the name 2185 * of the system on which the privilege name is retrieved. If a 2186 * null string is specified, the function attempts to find the 2187 * privilege name on the local system. 2188 * @param lpName 2189 * A pointer to a null-terminated string that specifies the name 2190 * of the privilege, as defined in the Winnt.h header file. For 2191 * example, this parameter could specify the constant, 2192 * SE_SECURITY_NAME, or its corresponding string, 2193 * "SeSecurityPrivilege". 2194 * @param lpLuid 2195 * A pointer to a variable that receives the LUID by which the 2196 * privilege is known on the system specified by the lpSystemName 2197 * parameter. 2198 * @return If the function succeeds, the return value is nonzero. If the 2199 * function fails, the return value is zero. To get extended error 2200 * information, call GetLastError. 2201 */ LookupPrivilegeValue(String lpSystemName, String lpName, WinNT.LUID lpLuid)2202 boolean LookupPrivilegeValue(String lpSystemName, String lpName, WinNT.LUID lpLuid); 2203 2204 /** 2205 * The function obtains specified information about the security of a file 2206 * or directory. The information obtained is constrained by the caller's 2207 * access rights and privileges. 2208 * 2209 * @param lpFileName 2210 * A pointer to a null-terminated string that specifies the file 2211 * or directory for which security information is retrieved. 2212 * @param RequestedInformation 2213 * A SECURITY_INFORMATION value that identifies the security 2214 * information being requested. See WinNT *_SECURITY_INFORMATION 2215 * @param pointer 2216 * A pointer to a buffer that receives a copy of the security 2217 * descriptor of the object specified by the lpFileName 2218 * parameter. The calling process must have permission to view 2219 * the specified aspects of the object's security status. The 2220 * SECURITY_DESCRIPTOR structure is returned in self-relative 2221 * format. 2222 * @param nLength 2223 * Specifies the size, in bytes, of the buffer pointed to by the 2224 * pSecurityDescriptor parameter. 2225 * @param lpnLengthNeeded 2226 * A pointer to the variable that receives the number of bytes 2227 * necessary to store the complete security descriptor. If the 2228 * returned number of bytes is less than or equal to nLength, the 2229 * entire security descriptor is returned in the output buffer; 2230 * otherwise, none of the descriptor is returned. 2231 * @return whether the call succeeded 2232 */ GetFileSecurity(String lpFileName, int RequestedInformation, Pointer pointer, int nLength, IntByReference lpnLengthNeeded)2233 boolean GetFileSecurity(String lpFileName, 2234 int RequestedInformation, Pointer pointer, int nLength, 2235 IntByReference lpnLengthNeeded); 2236 2237 /** 2238 * The SetFileSecurity function sets the security of a file or directory object. 2239 * This function is obsolete. Use the SetNamedSecurityInfo function instead. 2240 * 2241 * @param lpFileName 2242 * A pointer to a null-terminated string that specifies the file or directory for which security is set. 2243 * Note that security applied to a directory is not inherited by its children. 2244 * @param SecurityInformation 2245 * Specifies a SECURITY_INFORMATION structure that identifies the contents of the security descriptor 2246 * pointed to by the pSecurityDescriptor parameter. 2247 * @param pSecurityDescriptor 2248 * A pointer to a SECURITY_DESCRIPTOR structure. 2249 * @return 2250 * If the function succeeds, the function returns nonzero. If the function fails, it returns zero. To get 2251 * extended error information, call GetLastError. 2252 */ SetFileSecurity(String lpFileName, int SecurityInformation, Pointer pSecurityDescriptor)2253 boolean SetFileSecurity(String lpFileName, int SecurityInformation, Pointer pSecurityDescriptor); 2254 2255 /** 2256 * The GetSecurityInfo function retrieves a copy of the security descriptor for an object specified by a handle. 2257 * 2258 * @param handle [in] 2259 * A handle to the object from which to retrieve security information. 2260 * @param ObjectType [in] 2261 * SE_OBJECT_TYPE enumeration value that indicates the type of object. 2262 * @param SecurityInfo [in] 2263 * A set of bit flags that indicate the type of security information to retrieve. See WinNT *_SECURITY_INFORMATION 2264 * @param ppsidOwner [out, optional] 2265 * A pointer to a variable that receives a pointer to the owner SID in the security descriptor returned 2266 * in ppSecurityDescriptor. The returned pointer is valid only if you set the OWNER_SECURITY_INFORMATION flag. 2267 * This parameter can be NULL if you do not need the owner SID. 2268 * @param ppsidGroup [in, optional] 2269 * A pointer to a variable that receives a pointer to the primary group SID in the returned security descriptor. 2270 * The returned pointer is valid only if you set the GROUP_SECURITY_INFORMATION flag. This parameter can be NULL 2271 * if you do not need the group SID. 2272 * @param ppDacl [in, optional] 2273 * A pointer to a variable that receives a pointer to the DACL in the returned security descriptor. The returned 2274 * pointer is valid only if you set the DACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do not 2275 * need the DACL. 2276 * @param ppSacl [in, optional] 2277 * A pointer to a variable that receives a pointer to the SACL in the returned security descriptor. The returned 2278 * pointer is valid only if you set the SACL_SECURITY_INFORMATION flag. This parameter can be NULL if you do not 2279 * need the SACL. 2280 * @param ppSecurityDescriptor 2281 * A pointer to a variable that receives a pointer to the security descriptor of the object. When you have finished 2282 * using the pointer, free the returned buffer by calling the LocalFree function. 2283 * This parameter is required if any one of the ppsidOwner, ppsidGroup, ppDacl, or ppSacl parameters is not NULL. 2284 * @return whether the call succeeded. A nonzero return is a failure. 2285 * 2286 * <p><b>NOTES:</b></p> 2287 * <p>1. If the ppsidOwner, ppsidGroup, ppDacl, and ppSacl parameters are non-NULL, and the SecurityInfo parameter specifies 2288 * that they be retrieved from the object, those parameters will point to the corresponding parameters in the security descriptor 2289 * returned in ppSecurityDescriptor.</p> 2290 * <p>2. To read the owner, group, or DACL from the object's security descriptor, the calling process must have been granted 2291 * READ_CONTROL access when the handle was opened. To get READ_CONTROL access, the caller must be the owner of the object or 2292 * the object's DACL must grant the access.</p> 2293 * <p>3. To read the SACL from the security descriptor, the calling process must have been granted ACCESS_SYSTEM_SECURITY access 2294 * when the handle was opened. The proper way to get this access is to enable the SE_SECURITY_NAME privilege in the caller's 2295 * current token, open the handle for ACCESS_SYSTEM_SECURITY access, and then disable the privilege.</p> 2296 * <p>4. If the supplied handle was opened with an ACCESS_MASK value of MAXIMUM_ALLOWED, 2297 * then the SetSecurityInfo function will not propagate ACEs to children.</p> 2298 */ GetSecurityInfo(HANDLE handle, int ObjectType, int SecurityInfo, PointerByReference ppsidOwner, PointerByReference ppsidGroup, PointerByReference ppDacl, PointerByReference ppSacl, PointerByReference ppSecurityDescriptor)2299 int GetSecurityInfo(HANDLE handle, 2300 int ObjectType, 2301 int SecurityInfo, 2302 PointerByReference ppsidOwner, 2303 PointerByReference ppsidGroup, 2304 PointerByReference ppDacl, 2305 PointerByReference ppSacl, 2306 PointerByReference ppSecurityDescriptor); 2307 2308 /** 2309 * The SetSecurityInfo function sets specified security information in 2310 * the security descriptor of a specified object. The caller identifies the 2311 * object by a handle. 2312 * 2313 * @param handle [in] 2314 * A handle to the object for which to set security information. 2315 * @param ObjectType [in] 2316 * A value of the SE_OBJECT_TYPE enumeration that indicates the type 2317 * of object named by the pObjectName parameter. 2318 * @param SecurityInfo [in] 2319 * A set of bit flags that indicate the type of security 2320 * information to set. See WinNT *_SECURITY_INFORMATION 2321 * @param ppsidOwner [in, optional] 2322 * A pointer to a SID structure that identifies the owner of the object. 2323 * If the caller does not have the SeRestorePrivilege constant 2324 * (see Privilege Constants), this SID must be contained in the 2325 * caller's token, and must have the SE_GROUP_OWNER permission enabled. 2326 * The SecurityInfo parameter must include the OWNER_SECURITY_INFORMATION 2327 * flag. To set the owner, the caller must have WRITE_OWNER access to 2328 * the object or have the SE_TAKE_OWNERSHIP_NAME privilege enabled. 2329 * If you are not setting the owner SID, this parameter can be NULL. 2330 * @param ppsidGroup [in, optional] 2331 * A pointer to a SID that identifies the primary group of the object. 2332 * The SecurityInfo parameter must include the GROUP_SECURITY_INFORMATION 2333 * flag. If you are not setting the primary group SID, this parameter 2334 * can be NULL. 2335 * @param ppDacl [in, optional] 2336 * A pointer to the new DACL for the object. The SecurityInfo parameter 2337 * must include the DACL_SECURITY_INFORMATION flag. The caller must have 2338 * WRITE_DAC access to the object or be the owner of the object. If you 2339 * are not setting the DACL, this parameter can be NULL. 2340 * @param ppSacl [in, optional] 2341 * A pointer to the new SACL for the object. The SecurityInfo parameter 2342 * must include any of the following flags: SACL_SECURITY_INFORMATION, 2343 * LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION, 2344 * SCOPE_SECURITY_INFORMATION, or BACKUP_SECURITY_INFORMATION. 2345 * If setting SACL_SECURITY_INFORMATION or SCOPE_SECURITY_INFORMATION, 2346 * the caller must have the SE_SECURITY_NAME privilege enabled. If 2347 * you are not setting the SACL, this parameter can be NULL. 2348 * @return whether the call succeeded. A nonzero return is a failure. 2349 * 2350 * <p><b>NOTES:</b></p> 2351 * <p>1. If you are setting the discretionary access control list (DACL) or any elements 2352 * in the system access control list (SACL) of an object, the system automatically 2353 * propagates any inheritable access control entries (ACEs) to existing child objects, 2354 * according to the ACE inheritance rules.</p> 2355 * <p>2. The SetSecurityInfo function does not reorder access-allowed or access-denied 2356 * ACEs based on the preferred order. When propagating inheritable ACEs to existing 2357 * child objects, SetSecurityInfo puts inherited ACEs in order after all of the 2358 * noninherited ACEs in the DACLs of the child objects.</p> 2359 * <p>3. If share access to the children of the object is not available, this function 2360 * will not propagate unprotected ACEs to the children. For example, if a directory 2361 * is opened with exclusive access, the operating system will not propagate unprotected 2362 * ACEs to the subdirectories or files of that directory when the security on the 2363 * directory is changed.</p> 2364 * <p>4. If the supplied handle was opened with an ACCESS_MASK value of MAXIMUM_ALLOWED, 2365 * then the SetSecurityInfo function will not propagate ACEs to children.</p> 2366 */ SetSecurityInfo(HANDLE handle, int ObjectType, int SecurityInfo, Pointer ppsidOwner, Pointer ppsidGroup, Pointer ppDacl, Pointer ppSacl)2367 int SetSecurityInfo(HANDLE handle, 2368 int ObjectType, 2369 int SecurityInfo, 2370 Pointer ppsidOwner, 2371 Pointer ppsidGroup, 2372 Pointer ppDacl, 2373 Pointer ppSacl); 2374 2375 /** 2376 * The GetNamedSecurityInfo function retrieves a copy of the security 2377 * descriptor for an object specified by name 2378 * 2379 * @param pObjectName 2380 * A pointer to a that specifies the name of the object from 2381 * which to retrieve security information. 2382 * For descriptions of the string formats for the different 2383 * object types, see SE_OBJECT_TYPE. 2384 * @param ObjectType 2385 * Specifies a value from the SE_OBJECT_TYPE enumeration that 2386 * indicates the type of object named by the pObjectName parameter. 2387 * @param SecurityInfo 2388 * A set of bit flags that indicate the type of security 2389 * information to retrieve. See WinNT *_SECURITY_INFORMATION 2390 * @param ppsidOwner [out, optional] 2391 * A pointer to a variable that receives a pointer to the owner SID 2392 * in the security descriptor returned in ppSecurityDescriptor 2393 * or NULL if the security descriptor has no owner SID. 2394 * The returned pointer is valid only if you set the 2395 * OWNER_SECURITY_INFORMATION flag. Also, this parameter can be 2396 * NULL if you do not need the owner SID. 2397 * @param ppsidGroup [out, optional] 2398 * A pointer to a variable that receives a pointer to the primary 2399 * group SID in the returned security descriptor or NULL if the 2400 * security descriptor has no group SID. The returned pointer is 2401 * valid only if you set the GROUP_SECURITY_INFORMATION flag. 2402 * Also, this parameter can be NULL if you do not need the group SID. 2403 * @param ppDacl [out, optional] 2404 * A pointer to a variable that receives a pointer to the DACL in 2405 * the returned security descriptor or NULL if the security 2406 * descriptor has no DACL. The returned pointer is valid only if 2407 * you set the DACL_SECURITY_INFORMATION flag. Also, this parameter 2408 * can be NULL if you do not need the DACL. 2409 * @param ppSacl [out, optional] 2410 * A pointer to a variable that receives a pointer to the SACL in 2411 * the returned security descriptor or NULL if the security 2412 * descriptor has no SACL. The returned pointer is valid only if 2413 * you set the SACL_SECURITY_INFORMATION flag. Also, this parameter 2414 * can be NULL if you do not need the SACL. 2415 * @param ppSecurityDescriptor 2416 * A pointer to a variable that receives a pointer to the security 2417 * descriptor of the object. When you have finished using the 2418 * pointer, free the returned buffer by calling the LocalFree 2419 * function. 2420 * 2421 * This parameter is required if any one of the ppsidOwner, 2422 * ppsidGroup, ppDacl, or ppSacl parameters is not NULL. 2423 * @return whether the call succeeded. A nonzero return is a failure. 2424 * 2425 * NOTES: 2426 * 1. To read the owner, group, or DACL from the object's security descriptor, 2427 * the object's DACL must grant READ_CONTROL access to the caller, or the caller 2428 * must be the owner of the object. 2429 * 2. To read the system access control list of the object, the SE_SECURITY_NAME 2430 * privilege must be enabled for the calling process. For information about the 2431 * security implications of enabling privileges, see Running with Special Privileges. 2432 */ GetNamedSecurityInfo( String pObjectName, int ObjectType, int SecurityInfo, PointerByReference ppsidOwner, PointerByReference ppsidGroup, PointerByReference ppDacl, PointerByReference ppSacl, PointerByReference ppSecurityDescriptor)2433 int GetNamedSecurityInfo( 2434 String pObjectName, 2435 int ObjectType, 2436 int SecurityInfo, 2437 PointerByReference ppsidOwner, 2438 PointerByReference ppsidGroup, 2439 PointerByReference ppDacl, 2440 PointerByReference ppSacl, 2441 PointerByReference ppSecurityDescriptor); 2442 2443 /** 2444 * The SetNamedSecurityInfo function sets specified security information in 2445 * the security descriptor of a specified object. The caller identifies the 2446 * object by name. 2447 * 2448 * @param pObjectName [in] 2449 * A pointer to a string that specifies the name of the object for 2450 * which to set security information. This can be 2451 * the name of a local or remote file or directory on an NTFS file 2452 * system, network share, registry key, semaphore, event, mutex, 2453 * file mapping, or waitable timer. * 2454 * For descriptions of the string formats for the different 2455 * object types, see SE_OBJECT_TYPE. 2456 * @param ObjectType [in] 2457 * A value of the SE_OBJECT_TYPE enumeration that indicates the type 2458 * of object named by the pObjectName parameter. 2459 * @param SecurityInfo [in] 2460 * A set of bit flags that indicate the type of security 2461 * information to set. See WinNT *_SECURITY_INFORMATION 2462 * @param ppsidOwner [in, optional] 2463 * A pointer to a SID structure that identifies the owner of the object. 2464 * If the caller does not have the SeRestorePrivilege constant 2465 * (see Privilege Constants), this SID must be contained in the 2466 * caller's token, and must have the SE_GROUP_OWNER permission enabled. 2467 * The SecurityInfo parameter must include the OWNER_SECURITY_INFORMATION 2468 * flag. To set the owner, the caller must have WRITE_OWNER access to 2469 * the object or have the SE_TAKE_OWNERSHIP_NAME privilege enabled. 2470 * If you are not setting the owner SID, this parameter can be NULL. 2471 * @param ppsidGroup [in, optional] 2472 * A pointer to a SID that identifies the primary group of the object. 2473 * The SecurityInfo parameter must include the GROUP_SECURITY_INFORMATION 2474 * flag. If you are not setting the primary group SID, this parameter 2475 * can be NULL. 2476 * @param ppDacl [in, optional] 2477 * A pointer to the new DACL for the object. The SecurityInfo parameter 2478 * must include the DACL_SECURITY_INFORMATION flag. The caller must have 2479 * WRITE_DAC access to the object or be the owner of the object. If you 2480 * are not setting the DACL, this parameter can be NULL. 2481 * @param ppSacl [in, optional] 2482 * A pointer to the new SACL for the object. The SecurityInfo parameter 2483 * must include any of the following flags: SACL_SECURITY_INFORMATION, 2484 * LABEL_SECURITY_INFORMATION, ATTRIBUTE_SECURITY_INFORMATION, 2485 * SCOPE_SECURITY_INFORMATION, or BACKUP_SECURITY_INFORMATION. 2486 * If setting SACL_SECURITY_INFORMATION or SCOPE_SECURITY_INFORMATION, 2487 * the caller must have the SE_SECURITY_NAME privilege enabled. If 2488 * you are not setting the SACL, this parameter can be NULL. 2489 * @return whether the call succeeded. A nonzero return is a failure. 2490 * 2491 * NOTES: 2492 * 1. The SetNamedSecurityInfo function does not reorder access-allowed or access-denied 2493 * ACEs based on the preferred order. When propagating inheritable ACEs to existing 2494 * child objects, SetNamedSecurityInfo puts inherited ACEs in order after all of the 2495 * noninherited ACEs in the DACLs of the child objects. 2496 * 2. This function transfers information in plaintext. The information transferred by 2497 * this function is signed unless signing has been turned off for the system, but no 2498 * encryption is performed. 2499 * 3. When you update access rights of a folder indicated by an UNC path, for example 2500 * \\Test\TestFolder, the original inherited ACE is removed and the full volume path 2501 * is not included. 2502 */ SetNamedSecurityInfo( String pObjectName, int ObjectType, int SecurityInfo, Pointer ppsidOwner, Pointer ppsidGroup, Pointer ppDacl, Pointer ppSacl)2503 int SetNamedSecurityInfo( 2504 String pObjectName, 2505 int ObjectType, 2506 int SecurityInfo, 2507 Pointer ppsidOwner, 2508 Pointer ppsidGroup, 2509 Pointer ppDacl, 2510 Pointer ppSacl); 2511 2512 /** 2513 * The GetSecurityDescriptorLength function returns the length, in bytes, of a structurally 2514 * valid security descriptor. The length includes the length of all associated structures. 2515 * 2516 * @param ppSecurityDescriptor 2517 * A pointer to the SECURITY_DESCRIPTOR structure whose length the function returns. 2518 * The pointer is assumed to be valid. 2519 * @return If the function succeeds, the function returns the length, in bytes, of the SECURITY_DESCRIPTOR structure. 2520 * If the SECURITY_DESCRIPTOR structure is not valid, the return value is undefined. 2521 */ GetSecurityDescriptorLength(Pointer ppSecurityDescriptor)2522 int GetSecurityDescriptorLength(Pointer ppSecurityDescriptor); 2523 2524 /** 2525 * The IsValidSecurityDescriptor function determines whether the components of a security descriptor are valid. 2526 * 2527 * @param ppSecurityDescriptor [in] 2528 * A pointer to a SECURITY_DESCRIPTOR structure that the function validates. 2529 * @return If the components of the security descriptor are valid, the return value is nonzero. 2530 */ IsValidSecurityDescriptor(Pointer ppSecurityDescriptor)2531 boolean IsValidSecurityDescriptor(Pointer ppSecurityDescriptor); 2532 2533 /** 2534 * A pointer to a SECURITY_DESCRIPTOR structure in absolute format. The function creates a version of this security 2535 * descriptor in self-relative format without modifying the original. 2536 * @param pAbsoluteSD 2537 * A pointer to a SECURITY_DESCRIPTOR structure in absolute format. The function creates a version of this 2538 * security descriptor in self-relative format without modifying the original. 2539 * @param pSelfRelativeSD 2540 * A pointer to a buffer the function fills with a security descriptor in self-relative format. 2541 * @param lpdwBufferLength 2542 * A pointer to a variable specifying the size of the buffer pointed to by the pSelfRelativeSD parameter. 2543 * If the buffer is not large enough for the security descriptor, the function fails and sets this variable 2544 * to the minimum required size. 2545 * @return If the function succeeds, the function returns nonzero. If the function fails, it returns zero. To get 2546 * extended error information, call GetLastError. Possible return codes include, but are not limited to, the following: 2547 * ERROR_INSUFFICIENT_BUFFER - One or more of the buffers is too small. 2548 */ MakeSelfRelativeSD(SECURITY_DESCRIPTOR pAbsoluteSD, SECURITY_DESCRIPTOR_RELATIVE pSelfRelativeSD, IntByReference lpdwBufferLength)2549 boolean MakeSelfRelativeSD(SECURITY_DESCRIPTOR pAbsoluteSD, 2550 SECURITY_DESCRIPTOR_RELATIVE pSelfRelativeSD, 2551 IntByReference lpdwBufferLength); 2552 2553 /** 2554 * The MakeAbsoluteSD function creates a security descriptor in absolute format by using a 2555 * security descriptor in self-relative format as a template. 2556 * @param pSelfRelativeSD 2557 * A pointer to a SECURITY_DESCRIPTOR structure in self-relative format. The function creates an 2558 * absolute-format version of this security descriptor without modifying the original security descriptor. 2559 * @param pAbsoluteSD 2560 * A pointer to a buffer that the function fills with the main body of an absolute-format security 2561 * descriptor. This information is formatted as a SECURITY_DESCRIPTOR structure. 2562 * @param lpdwAbsoluteSDSize 2563 * A pointer to a variable that specifies the size of the buffer pointed to by the pAbsoluteSD parameter. 2564 * If the buffer is not large enough for the security descriptor, the function fails and sets this variable 2565 * to the minimum required size. 2566 * @param pDacl 2567 * A pointer to a buffer the function fills with the discretionary access control list (DACL) of the 2568 * absolute-format security descriptor. The main body of the absolute-format security descriptor references 2569 * this pointer. 2570 * @param lpdwDaclSize 2571 * A pointer to a variable that specifies the size of the buffer pointed to by the pDacl parameter. If 2572 * the buffer is not large enough for the access control list (ACL), the function fails and sets this 2573 * variable to the minimum required size. 2574 * @param pSacl 2575 * A pointer to a buffer the function fills with the system access control list (SACL) of the absolute-format 2576 * security descriptor. The main body of the absolute-format security descriptor references this pointer. 2577 * @param lpdwSaclSize 2578 * A pointer to a variable that specifies the size of the buffer pointed to by the pSacl parameter. If the 2579 * buffer is not large enough for the ACL, the function fails and sets this variable to the minimum required 2580 * size. 2581 * @param pOwner 2582 * A pointer to a buffer the function fills with the security identifier (SID) of the owner of the 2583 * absolute-format security descriptor. The main body of the absolute-format security descriptor references 2584 * this pointer. 2585 * @param lpdwOwnerSize 2586 * A pointer to a variable that specifies the size of the buffer pointed to by the pOwner parameter. 2587 * If the buffer is not large enough for the SID, the function fails and sets this variable to the minimum 2588 * required size. 2589 * @param pPrimaryGroup 2590 * A pointer to a buffer the function fills with the SID of the absolute-format security descriptor's 2591 * primary group. The main body of the absolute-format security descriptor references this pointer. 2592 * @param lpdwPrimaryGroupSize 2593 * A pointer to a variable that specifies the size of the buffer pointed to by the pPrimaryGroup parameter. 2594 * If the buffer is not large enough for the SID, the function fails and sets this variable to the minimum 2595 * required size. 2596 * @return If the function succeeds, the function returns nonzero. If the function fails, it returns zero. To get 2597 * extended error information, call GetLastError. Possible return codes include, but are not limited to, the following: 2598 * ERROR_INSUFFICIENT_BUFFER - One or more of the buffers is too small. 2599 */ MakeAbsoluteSD(SECURITY_DESCRIPTOR_RELATIVE pSelfRelativeSD, SECURITY_DESCRIPTOR pAbsoluteSD, IntByReference lpdwAbsoluteSDSize, ACL pDacl, IntByReference lpdwDaclSize, ACL pSacl, IntByReference lpdwSaclSize, PSID pOwner, IntByReference lpdwOwnerSize, PSID pPrimaryGroup, IntByReference lpdwPrimaryGroupSize)2600 boolean MakeAbsoluteSD(SECURITY_DESCRIPTOR_RELATIVE pSelfRelativeSD, 2601 SECURITY_DESCRIPTOR pAbsoluteSD, 2602 IntByReference lpdwAbsoluteSDSize, 2603 ACL pDacl, 2604 IntByReference lpdwDaclSize, 2605 ACL pSacl, 2606 IntByReference lpdwSaclSize, 2607 PSID pOwner, 2608 IntByReference lpdwOwnerSize, 2609 PSID pPrimaryGroup, 2610 IntByReference lpdwPrimaryGroupSize); 2611 2612 /** 2613 * The IsValidAcl function validates an access control list (ACL). 2614 * 2615 * @param pAcl [in] 2616 * A pointer to an ACL structure validated by this function. This value must not be NULL. 2617 * @return If the ACL is valid, the function returns nonzero. If the ACL is not valid, the function returns zero. 2618 * There is no extended error information for this function; do not call GetLastError. 2619 * 2620 * This function checks the revision level of the ACL and verifies that the number of access control entries 2621 * (ACEs) specified in the AceCount member of the ACL structure fits the space specified by the AclSize member 2622 * of the ACL structure.If pAcl is NULL, the application will fail with an access violation. 2623 */ IsValidAcl(Pointer pAcl)2624 boolean IsValidAcl(Pointer pAcl); 2625 2626 /** 2627 * Applies the given mapping of generic access rights to the given access mask. 2628 * @param AccessMask [in, out] A pointer to an access mask. 2629 * @param GenericMapping [in] A pointer to a GENERIC_MAPPING structure specifying a mapping of generic access types to specific and standard access types. 2630 */ MapGenericMask(DWORDByReference AccessMask, GENERIC_MAPPING GenericMapping)2631 void MapGenericMask(DWORDByReference AccessMask, GENERIC_MAPPING GenericMapping); 2632 2633 2634 /** 2635 * Check if the if the security descriptor grants access to the given client token. 2636 * 2637 * @param pSecurityDescriptor [in] A pointer to a SECURITY_DESCRIPTOR structure against which access is checked. 2638 * @param ClientToken [in] A handle to an impersonation token that represents the client that is attempting to gain access. The handle must have TOKEN_QUERY access to the token; otherwise, the function fails with ERROR_ACCESS_DENIED. 2639 * @param DesiredAccess [in] Access mask that specifies the access rights to check. This mask must have been mapped by the MapGenericMask function to contain no generic access rights.<br> 2640 * If this parameter is MAXIMUM_ALLOWED, the function sets the GrantedAccess access mask to indicate the maximum access rights the security descriptor allows the client. 2641 * @param GenericMapping [in] A pointer to the GENERIC_MAPPING structure associated with the object for which access is being checked. 2642 * @param PrivilegeSet [out, optional] A pointer to a PRIVILEGE_SET structure that receives the privileges used to perform the access validation. If no privileges were used, the function sets the PrivilegeCount member to zero. 2643 * @param PrivilegeSetLength [in, out] Specifies the size, in bytes, of the buffer pointed to by the PrivilegeSet parameter. 2644 * @param GrantedAccess [out] A pointer to an access mask that receives the granted access rights. If AccessStatus is set to FALSE, the function sets the access mask to zero. If the function fails, it does not set the access mask. 2645 * @param AccessStatus [out] A pointer to a variable that receives the results of the access check. If the security descriptor allows the requested access rights to the client identified by the access token, AccessStatus is set to TRUE. Otherwise, AccessStatus is set to FALSE, and you can call GetLastError to get extended error information. 2646 * @return true on success; false on failure (use GetLastError to get extended error information) 2647 */ AccessCheck(Pointer pSecurityDescriptor, HANDLE ClientToken, DWORD DesiredAccess, GENERIC_MAPPING GenericMapping, PRIVILEGE_SET PrivilegeSet, DWORDByReference PrivilegeSetLength, DWORDByReference GrantedAccess, BOOLByReference AccessStatus)2648 boolean AccessCheck(Pointer pSecurityDescriptor, 2649 HANDLE ClientToken, DWORD DesiredAccess, 2650 GENERIC_MAPPING GenericMapping, 2651 PRIVILEGE_SET PrivilegeSet, 2652 DWORDByReference PrivilegeSetLength, 2653 DWORDByReference GrantedAccess, BOOLByReference AccessStatus); 2654 2655 /** 2656 * Encrypts a file or directory. All data streams in a file are encrypted. All 2657 * new files created in an encrypted directory are encrypted. 2658 * 2659 * @param lpFileName 2660 * The name of the file or directory to be encrypted. 2661 * @return If the function succeeds, the return value is nonzero. If the 2662 * function fails, the return value is zero. To get extended error 2663 * information, call GetLastError. 2664 */ EncryptFile(String lpFileName)2665 boolean EncryptFile(String lpFileName); 2666 2667 /** 2668 * Decrypts an encrypted file or directory. 2669 * 2670 * @param lpFileName 2671 * The name of the file or directory to be decrypted. 2672 * @param dwReserved 2673 * Reserved; must be zero. 2674 * @return If the function succeeds, the return value is nonzero. If the 2675 * function fails, the return value is zero. To get extended error 2676 * information, call GetLastError. 2677 */ DecryptFile(String lpFileName, DWORD dwReserved)2678 boolean DecryptFile(String lpFileName, DWORD dwReserved); 2679 2680 /** 2681 * Retrieves the encryption status of the specified file. 2682 * 2683 * @param lpFileName 2684 * The name of the file. 2685 * @param lpStatus 2686 * A pointer to a variable that receives the encryption status of the 2687 * file. 2688 * @return If the function succeeds, the return value is nonzero. If the 2689 * function fails, the return value is zero. To get extended error 2690 * information, call GetLastError. 2691 */ FileEncryptionStatus(String lpFileName, DWORDByReference lpStatus)2692 boolean FileEncryptionStatus(String lpFileName, DWORDByReference lpStatus); 2693 2694 /** 2695 * Disables or enables encryption of the specified directory and the files in 2696 * it. It does not affect encryption of subdirectories below the indicated 2697 * directory. 2698 * 2699 * @param DirPath 2700 * The name of the directory for which to enable or disable 2701 * encryption. 2702 * @param Disable 2703 * Indicates whether to disable encryption (TRUE) or enable it 2704 * (FALSE). 2705 * @return If the function succeeds, the return value is nonzero. If the 2706 * function fails, the return value is zero. To get extended error 2707 * information, call GetLastError. 2708 */ EncryptionDisable(String DirPath, boolean Disable)2709 boolean EncryptionDisable(String DirPath, boolean Disable); 2710 2711 /** 2712 * Opens an encrypted file in order to backup (export) or restore (import) the 2713 * file. This is one of a group of Encrypted File System (EFS) functions that 2714 * is intended to implement backup and restore functionality, while 2715 * maintaining files in their encrypted state. 2716 * 2717 * @param lpFileName 2718 * The name of the file to be opened. The string must consist of 2719 * characters from the Windows character set. 2720 * @param ulFlags 2721 * The operation to be performed. 2722 * @param pvContext 2723 * The address of a context block that must be presented in subsequent 2724 * calls to ReadEncryptedFileRaw, WriteEncryptedFileRaw, or 2725 * CloseEncryptedFileRaw. Do not modify it. 2726 * @return If the function succeeds, it returns ERROR_SUCCESS. If the function 2727 * fails, it returns a nonzero error code defined in WinError.h. You can use 2728 * FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic 2729 * text description of the error. 2730 */ OpenEncryptedFileRaw(String lpFileName, ULONG ulFlags, PointerByReference pvContext)2731 int OpenEncryptedFileRaw(String lpFileName, ULONG ulFlags, PointerByReference pvContext); 2732 2733 /** 2734 * Backs up (export) encrypted files. This is one of a group of Encrypted File 2735 * System (EFS) functions that is intended to implement backup and restore 2736 * functionality, while maintaining files in their encrypted state. 2737 * 2738 * @param pfExportCallback 2739 * A pointer to the export callback function. The system calls the 2740 * callback function multiple times, each time passing a block of the 2741 * file's data to the callback function until the entire file has been 2742 * read. For more information, see ExportCallback. 2743 * @param pvCallbackContext 2744 * A pointer to an application-defined and allocated context block. 2745 * The system passes this pointer to the callback function as a 2746 * parameter so that the callback function can have access to 2747 * application-specific data. This can be a structure and can contain 2748 * any data the application needs, such as the handle to the file that 2749 * will contain the backup copy of the encrypted file. 2750 * @param pvContext 2751 * A pointer to a system-defined context block. The context block is 2752 * returned by the OpenEncryptedFileRaw function. Do not modify it. 2753 * @return If the function succeeds, the return value is ERROR_SUCCESS. If the 2754 * function fails, it returns a nonzero error code defined in WinError.h. You 2755 * can use FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a 2756 * generic text description of the error. 2757 */ ReadEncryptedFileRaw(FE_EXPORT_FUNC pfExportCallback, Pointer pvCallbackContext, Pointer pvContext)2758 int ReadEncryptedFileRaw(FE_EXPORT_FUNC pfExportCallback, 2759 Pointer pvCallbackContext, Pointer pvContext); 2760 2761 /** 2762 * Restores (import) encrypted files. This is one of a group of Encrypted File 2763 * System (EFS) functions that is intended to implement backup and restore 2764 * functionality, while maintaining files in. 2765 * 2766 * @param pfImportCallback 2767 * A pointer to the import callback function. The system calls the 2768 * callback function multiple times, each time passing a buffer that 2769 * will be filled by the callback function with a portion of backed-up 2770 * file's data. When the callback function signals that the entire 2771 * file has been processed, it tells the system that the restore 2772 * operation is finished. For more information, see ImportCallback. 2773 * @param pvCallbackContext 2774 * A pointer to an application-defined and allocated context block. 2775 * The system passes this pointer to the callback function as a 2776 * parameter so that the callback function can have access to 2777 * application-specific data. This can be a structure and can contain 2778 * any data the application needs, such as the handle to the file that 2779 * will contain the backup copy of the encrypted file. 2780 * @param pvContext 2781 * A pointer to a system-defined context block. The context block is 2782 * returned by the OpenEncryptedFileRaw function. Do not modify it. 2783 * @return If the function succeeds, the return value is ERROR_SUCCESS. If the 2784 * function fails, it returns a nonzero error code defined in WinError.h. You 2785 * can use FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a 2786 * generic text description of the error. 2787 */ WriteEncryptedFileRaw(FE_IMPORT_FUNC pfImportCallback, Pointer pvCallbackContext, Pointer pvContext)2788 int WriteEncryptedFileRaw(FE_IMPORT_FUNC pfImportCallback, 2789 Pointer pvCallbackContext, Pointer pvContext); 2790 2791 /** 2792 * Closes an encrypted file after a backup or restore operation, and frees 2793 * associated system resources. This is one of a group of Encrypted File 2794 * System (EFS) functions that is intended to implement backup and restore 2795 * functionality, while maintaining files in their encrypted state. 2796 * 2797 * @param pvContext 2798 * A pointer to a system-defined context block. The 2799 * OpenEncryptedFileRaw function returns the context block. 2800 */ CloseEncryptedFileRaw(Pointer pvContext)2801 void CloseEncryptedFileRaw(Pointer pvContext); 2802 2803 /** 2804 * <code> 2805 BOOL WINAPI CreateProcessWithLogonW( 2806 _In_ LPCWSTR lpUsername, 2807 _In_opt_ LPCWSTR lpDomain, 2808 _In_ LPCWSTR lpPassword, 2809 _In_ DWORD dwLogonFlags, 2810 _In_opt_ LPCWSTR lpApplicationName, 2811 _Inout_opt_ LPWSTR lpCommandLine, 2812 _In_ DWORD dwCreationFlags, 2813 _In_opt_ LPVOID lpEnvironment, 2814 _In_opt_ LPCWSTR lpCurrentDirectory, 2815 _In_ LPSTARTUPINFOW lpStartupInfo, 2816 _Out_ LPPROCESS_INFORMATION lpProcessInfo 2817 ); 2818 * </code> 2819 * 2820 * @param lpUsername 2821 * [in]<br> 2822 * The name of the user. This is the name of the user account to 2823 * log on to. <br> 2824 * If you use the UPN format, user@DNS_domain_name, the lpDomain 2825 * parameter must be NULL.<br> 2826 * The user account must have the Log On Locally permission on 2827 * the local computer. <br> 2828 * This permission is granted to all users on workstations and 2829 * servers, but only to administrators on domain controllers. 2830 * @param lpDomain 2831 * [in, optional]<br> 2832 * The name of the domain or server whose account database 2833 * contains the lpUsername account. <br> 2834 * If this parameter is NULL, the user name must be specified in 2835 * UPN format. 2836 * @param lpPassword 2837 * [in]<br> 2838 * The clear-text password for the lpUsername account. 2839 * @param dwLogonFlags 2840 * [in]<br> 2841 * The logon option. This parameter can be 0 (zero) or one of the 2842 * following values. <br> 2843 * LOGON_WITH_PROFILE: 0x00000001<br> 2844 * Log on, then load the user profile in the HKEY_USERS registry 2845 * key.<br> 2846 * The function returns after the profile is loaded. <br> 2847 * Loading the profile can be time-consuming, so it is best to 2848 * use this value only if you must access the information in the 2849 * HKEY_CURRENT_USER registry key.<br> 2850 * Windows Server 2003: The profile is unloaded after the new 2851 * process is terminated, whether or not it has created child 2852 * processes.<br> 2853 * Windows XP: The profile is unloaded after the new process and 2854 * all child processes it has created are terminated.<br> 2855 * <br> 2856 * LOGON_NETCREDENTIALS_ONLY: 0x00000002<br> 2857 * Log on, but use the specified credentials on the network only. 2858 * <br> 2859 * The new process uses the same token as the caller, but the 2860 * system creates a new logon session within LSA, and the process 2861 * uses the specified credentials as the default credentials. 2862 * <br> 2863 * This value can be used to create a process that uses a 2864 * different set of credentials locally than it does remotely. 2865 * <br> 2866 * This is useful in inter-domain scenarios where there is no 2867 * trust relationship.<br> 2868 * The system does not validate the specified credentials.<br> 2869 * Therefore, the process can start, but it may not have access 2870 * to network resources. 2871 * @param lpApplicationName 2872 * [in, optional]<br> 2873 * The name of the module to be executed. This module can be a 2874 * Windows-based application.<br> 2875 * It can be some other type of module (for example, MS-DOS or 2876 * OS/2) if the appropriate subsystem is available on the local 2877 * computer. The string can specify the full path and file name 2878 * of the module to execute or it can specify a partial name. 2879 * <br> 2880 * If it is a partial name, the function uses the current drive 2881 * and current directory to complete the specification. <br> 2882 * The function does not use the search path. This parameter must 2883 * include the file name extension; no default extension is 2884 * assumed. The lpApplicationName parameter can be NULL, and the 2885 * module name must be the first white space-delimited token in 2886 * the lpCommandLine string.<br> 2887 * If you are using a long file name that contains a space, use 2888 * quoted strings to indicate where the file name ends and the 2889 * arguments begin; otherwise, the file name is ambiguous. For 2890 * example, the following string can be interpreted in different 2891 * ways:<br> 2892 * "c:\program files\sub dir\program name"<br> 2893 * The system tries to interpret the possibilities in the 2894 * following order:<br> 2895 * <br> 2896 * c:\program.exe files\sub dir\program name<br> 2897 * c:\program files\sub.exe dir\program name<br> 2898 * c:\program files\sub dir\program.exe name<br> 2899 * c:\program files\sub dir\program name.exe<br> 2900 * <br> 2901 * If the executable module is a 16-bit application, 2902 * lpApplicationName should be NULL, and the string pointed to by 2903 * lpCommandLine should specify the executable module and its 2904 * arguments. 2905 * @param lpCommandLine 2906 * [in, out, optional]<br> 2907 * The command line to be executed. The maximum length of this 2908 * string is 1024 characters. <br> 2909 * If lpApplicationName is NULL, the module name portion of 2910 * lpCommandLine is limited to MAX_PATH characters.<br> 2911 * The function can modify the contents of this string. <br> 2912 * Therefore, this parameter cannot be a pointer to read-only 2913 * memory (such as a const variable or a literal string).<br> 2914 * If this parameter is a constant string, the function may cause 2915 * an access violation.<br> 2916 * The lpCommandLine parameter can be NULL, and the function uses 2917 * the string pointed to by lpApplicationNameas the command line. 2918 * <br> 2919 * <br> 2920 * If both lpApplicationName and lpCommandLine are non-NULL, 2921 * *lpApplicationName specifies the module to execute, and 2922 * *lpCommandLine specifies the command line.<br> 2923 * The new process can use GetCommandLine to retrieve the entire 2924 * command line.<br> 2925 * Console processes written in C can use the argc and argv 2926 * arguments to parse the command line. <br> 2927 * Because argv[0] is the module name, C programmers typically 2928 * repeat the module name as the first token in the command line. 2929 * <br> 2930 * If lpApplicationName is NULL, the first white space-delimited 2931 * token of the command line specifies the module name.<br> 2932 * If you are using a long file name that contains a space, use 2933 * quoted strings to indicate where the file name ends and the 2934 * arguments begin (see the explanation for the lpApplicationName 2935 * parameter). If the file name does not contain an extension, 2936 * .exe is appended. Therefore, if the file name extension is 2937 * .com, this parameter must include the .com extension. If the 2938 * file name ends in a period with no extension, or if the file 2939 * name contains a path, .exe is not appended. If the file name 2940 * does not contain a directory path, the system searches for the 2941 * executable file in the following sequence:<br> 2942 * <br> 2943 * 1. The directory from which the application loaded.<br> 2944 * 2. The current directory for the parent process.<br> 2945 * 3. The 32-bit Windows system directory. Use the 2946 * GetSystemDirectory function to get the path of this directory. 2947 * <br> 2948 * 4. The 16-bit Windows system directory. There is no function 2949 * that obtains the path of this directory, but it is searched. 2950 * <br> 2951 * 5. The Windows directory. Use the GetWindowsDirectory function 2952 * to get the path of this directory.<br> 2953 * 6. The directories that are listed in the PATH environment 2954 * variable. Note that this function does not search the 2955 * per-application path specified by the App Paths registry key. 2956 * To include this per-application path in the search sequence, 2957 * use the ShellExecute function.<br> 2958 * <br> 2959 * The system adds a null character to the command line string to 2960 * separate the file name from the arguments. This divides the 2961 * original string into two strings for internal processing.<br> 2962 * @param dwCreationFlags 2963 * The flags that control how the process is created. <br> 2964 * The CREATE_DEFAULT_ERROR_MODE, CREATE_NEW_CONSOLE, and 2965 * CREATE_NEW_PROCESS_GROUP flags are enabled by default. <br> 2966 * Even if you do not set the flag, the system functions as if it 2967 * were set. You can specify additional flags as noted.<br> 2968 * <br> 2969 * CREATE_DEFAULT_ERROR_MODE: 0x04000000<br> 2970 * The new process does not inherit the error mode of the calling 2971 * process. <br> 2972 * Instead, CreateProcessWithLogonW gives the new process the 2973 * current default error mode. <br> 2974 * An application sets the current default error mode by calling 2975 * SetErrorMode. This flag is enabled by default.<br> 2976 * <br> 2977 * CREATE_NEW_CONSOLE: 0x00000010<br> 2978 * The new process has a new console, instead of inheriting the 2979 * parent's console. This flag cannot be used with the 2980 * DETACHED_PROCESS flag.<br> 2981 * This flag is enabled by default.<br> 2982 * <br> 2983 * CREATE_NEW_PROCESS_GROUP: 0x00000200<br> 2984 * The new process is the root process of a new process group. 2985 * <br> 2986 * The process group includes all processes that are descendants 2987 * of this root process.<br> 2988 * The process identifier of the new process group is the same as 2989 * the process identifier, which is returned in the lpProcessInfo 2990 * parameter.<br> 2991 * Process groups are used by the GenerateConsoleCtrlEvent 2992 * function to enable sending a CTRL+C or CTRL+BREAK signal to a 2993 * group of console processes.<br> 2994 * This flag is enabled by default.<br> 2995 * <br> 2996 * CREATE_SEPARATE_WOW_VDM: 0x00000800<br> 2997 * This flag is only valid starting a 16-bit Windows-based 2998 * application.<br> 2999 * If set, the new process runs in a private Virtual DOS Machine 3000 * (VDM).<br> 3001 * By default, all 16-bit Windows-based applications run in a 3002 * single, shared VDM.<br> 3003 * The advantage of running separately is that a crash only 3004 * terminates the single VDM; any other programs running in 3005 * distinct VDMs continue to function normally.<br> 3006 * Also, 16-bit Windows-based applications that run in separate 3007 * VDMs have separate input queues, which means that if one 3008 * application stops responding momentarily, applications in 3009 * separate VDMs continue to receive input. <br> 3010 * CREATE_SUSPENDED: 0x00000004<br> 3011 * The primary thread of the new process is created in a 3012 * suspended state, and does not run until the ResumeThread 3013 * function is called.<br> 3014 * <br> 3015 * CREATE_UNICODE_ENVIRONMENT: 0x00000400<br> 3016 * Indicates the format of the lpEnvironment parameter.<br> 3017 * If this flag is set, the environment block pointed to by 3018 * lpEnvironment uses Unicode characters. <br> 3019 * Otherwise, the environment block uses ANSI characters. <br> 3020 * EXTENDED_STARTUPINFO_PRESENT: 0x00080000<br> 3021 * The process is created with extended startup information; the 3022 * lpStartupInfo parameter specifies a STARTUPINFOEX structure. 3023 * <br> 3024 * Windows Server 2003 and Windows XP: This value is not 3025 * supported.<br> 3026 * @param lpEnvironment 3027 * [in, optional]<br> 3028 * A pointer to an environment block for the new process.<br> 3029 * If this parameter is NULL, the new process uses an environment 3030 * created from the profile of the user specified by lpUsername. 3031 * An environment block consists of a null-terminated block of 3032 * null-terminated strings.<br> 3033 * Each string is in the following form:<br> 3034 * name=value<br> 3035 * Because the equal sign (=) is used as a separator, it must not 3036 * be used in the name of an environment variable.<br> 3037 * An environment block can contain Unicode or ANSI characters. 3038 * <br> 3039 * If the environment block pointed to by lpEnvironment contains 3040 * Unicode characters, ensure that dwCreationFlags includes 3041 * CREATE_UNICODE_ENVIRONMENT.<br> 3042 * If this parameter is NULL and the environment block of the 3043 * parent process contains Unicode characters, you must also 3044 * ensure that dwCreationFlags includes 3045 * CREATE_UNICODE_ENVIRONMENT.<br> 3046 * An ANSI environment block is terminated by two 0 (zero) bytes: 3047 * one for the last string and one more to terminate the block. 3048 * <br> 3049 * A Unicode environment block is terminated by four zero bytes: 3050 * two for the last string and two more to terminate the block. 3051 * <br> 3052 * To retrieve a copy of the environment block for a specific 3053 * user, use the CreateEnvironmentBlock function.<br> 3054 * @param lpCurrentDirectory 3055 * [in, optional]<br> 3056 * The full path to the current directory for the process.<br> 3057 * The string can also specify a UNC path.<br> 3058 * If this parameter is NULL, the new process has the same 3059 * current drive and directory as the calling process.<br> 3060 * This feature is provided primarily for shells that need to 3061 * start an application, and specify its initial drive and 3062 * working directory.<br> 3063 * @param lpStartupInfo 3064 * [in]<br> 3065 * A pointer to a STARTUPINFO or STARTUPINFOEX structure. <br> 3066 * The application must add permission for the specified user 3067 * account to the specified window station and desktop, even for 3068 * WinSta0\Default.<br> 3069 * If the lpDesktop member is NULL or an empty string, the new 3070 * process inherits the desktop and window station of its parent 3071 * process.<br> 3072 * The application must add permission for the specified user 3073 * account to the inherited window station and desktop.<br> 3074 * Windows XP: CreateProcessWithLogonW adds permission for the 3075 * specified user account to the inherited window station and 3076 * desktop.<br> 3077 * Handles in STARTUPINFO or STARTUPINFOEX must be closed with 3078 * CloseHandle when they are no longer needed.<br> 3079 * Important If the dwFlags member of the STARTUPINFO structure 3080 * specifies STARTF_USESTDHANDLES, the standard handle fields are 3081 * copied unchanged to the child process without validation.<br> 3082 * The caller is responsible for ensuring that these fields 3083 * contain valid handle values. Incorrect values can cause the 3084 * child process to misbehave or crash.<br> 3085 * Use the Application Verifier runtime verification tool to 3086 * detect invalid handles. 3087 * @param lpProcessInfo 3088 * [out]<br> 3089 * A pointer to a PROCESS_INFORMATION structure that receives 3090 * identification information for the new process, including a 3091 * handle to the process.<br> 3092 * Handles in PROCESS_INFORMATION must be closed with the 3093 * CloseHandle function when they are not needed.<br> 3094 * @return If the function succeeds, the return value is nonzero.<br> 3095 * If the function fails, the return value is 0 (zero).<br> 3096 * To get extended error information, call GetLastError.<br> 3097 * Note that the function returns before the process has finished 3098 * initialization.<br> 3099 * If a required DLL cannot be located or fails to initialize, the 3100 * process is terminated.<br> 3101 * To get the termination status of a process, call 3102 * GetExitCodeProcess. 3103 * @see <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/ms682431%28v=vs.85%29.aspx">MSDN</a> 3104 */ CreateProcessWithLogonW(String lpUsername, String lpDomain, String lpPassword, int dwLogonFlags, String lpApplicationName, String lpCommandLine, int dwCreationFlags, Pointer lpEnvironment, String lpCurrentDirectory, STARTUPINFO lpStartupInfo, PROCESS_INFORMATION lpProcessInfo)3105 boolean CreateProcessWithLogonW(String lpUsername, String lpDomain, String lpPassword, int dwLogonFlags, 3106 String lpApplicationName, String lpCommandLine, int dwCreationFlags, Pointer lpEnvironment, 3107 String lpCurrentDirectory, STARTUPINFO lpStartupInfo, PROCESS_INFORMATION lpProcessInfo); 3108 3109 /** 3110 * Connects the main thread of a service process to the service control 3111 * manager, which causes the thread to be the service control dispatcher 3112 * thread for the calling process. 3113 * 3114 * @param lpServiceTable A pointer to an array of SERVICE_TABLE_ENTRY 3115 * structures containing one entry for each service 3116 * that can execute in the calling process. The 3117 * members of the last entry in the table must have 3118 * NULL values to designate the end of the table. 3119 * 3120 * @return true if function succeeds. To get extended error information, call 3121 * GetLastError. Possible error codes: 3122 * <table> 3123 * <tr><th>Return code</th><th>Description</th></tr> 3124 * <tr><td>ERROR_FAILED_SERVICE_CONTROLLER_CONNECT</td><td>This error is returned if the program is being run as a console application rather than as a service. If the program will be run as a console application for debugging purposes, structure it such that service-specific code is not called when this error is returned.</td></tr> 3125 * <tr><td>ERROR_INVALID_DATA</td><td>The specified dispatch table contains entries that are not in the proper format.</td></tr> 3126 * <tr><td>ERROR_SERVICE_ALREADY_RUNNING</td><td>The process has already called StartServiceCtrlDispatcher. Each process can call StartServiceCtrlDispatcher only one time.</td></tr> 3127 * </table> 3128 */ StartServiceCtrlDispatcher(SERVICE_TABLE_ENTRY[] lpServiceTable)3129 public boolean StartServiceCtrlDispatcher(SERVICE_TABLE_ENTRY[] lpServiceTable); 3130 3131 /** 3132 * Registers a function to handle service control requests. 3133 * 3134 * <p>This function has been superseded by the RegisterServiceCtrlHandlerEx 3135 * function. A service can use either function, but the new function 3136 * supports user-defined context data, and the new handler function supports 3137 * additional extended control codes.</p> 3138 * 3139 * @param lpServiceName The name of the service run by the calling thread. 3140 * This is the service name that the service control 3141 * program specified in the CreateService function when 3142 * creating the service. 3143 * 3144 * <p>If the service type is SERVICE_WIN32_OWN_PROCESS, 3145 * the function does not verify that the specified name 3146 * is valid, because there is only one registered 3147 * service in the process.</p> 3148 * 3149 * @param lpHandlerProc A pointer to the handler function to be registered. 3150 * For more information, see 3151 * {@link com.sun.jna.platform.win32.Winsvc.Handler WinSvc.Handler}. 3152 * 3153 * @return A service status handle, NULL on error. Call GetLastError to 3154 * get extended error condition. Possible error codes: 3155 * <table> 3156 * <tr><th>Return code</th><th>Description</th></tr> 3157 * <tr><td>ERROR_NOT_ENOUGH_MEMORY</td><td>Not enough memory is available to convert an ANSI string parameter to Unicode. This error does not occur for Unicode string parameters.</td></tr> 3158 * <tr><td>ERROR_SERVICE_NOT_IN_EXE</td><td>The service entry was specified incorrectly when the process called the {@link #StartServiceCtrlDispatcher} function.</td></tr> 3159 * </table> 3160 */ RegisterServiceCtrlHandler(String lpServiceName, Handler lpHandlerProc)3161 public SERVICE_STATUS_HANDLE RegisterServiceCtrlHandler(String lpServiceName, 3162 Handler lpHandlerProc); 3163 3164 /** 3165 * Registers a function to handle extended service control requests. 3166 * 3167 * @param lpServiceName The name of the service run by the calling thread. 3168 * This is the service name that the service control 3169 * program specified in the CreateService function when 3170 * creating the service. 3171 * @param lpHandlerProc The handler function to be registered. 3172 * For more information, see HandlerEx. 3173 * @param lpContext Any user-defined data. This parameter, which is 3174 * passed to the handler function, can help identify 3175 * the service when multiple services share a process. 3176 * 3177 * @return A service status handle on success, NULL on error. Call GetLastError 3178 * to get extended information. Possible error codes: 3179 * <table> 3180 * <tr><th>Return code</th><th>Description</th></tr> 3181 * <tr><td>ERROR_NOT_ENOUGH_MEMORY</td><td>Not enough memory is available to convert an ANSI string parameter to Unicode. This error does not occur for Unicode string parameters.</td></tr> 3182 * <tr><td>ERROR_SERVICE_NOT_IN_EXE</td><td>The service entry was specified incorrectly when the process called the {@link #StartServiceCtrlDispatcher} function.</td></tr> 3183 * </table> 3184 */ RegisterServiceCtrlHandlerEx(String lpServiceName, HandlerEx lpHandlerProc, Pointer lpContext)3185 public SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerEx(String lpServiceName, 3186 HandlerEx lpHandlerProc, Pointer lpContext); 3187 3188 /** 3189 * Updates the service control manager's status information for the calling 3190 * service. 3191 * 3192 * 3193 * @param hServiceStatus A handle to the status information structure for 3194 * the current service. This handle is returned by 3195 * the RegisterServiceCtrlHandlerEx function. 3196 * @param lpServiceStatus A pointer to the SERVICE_STATUS structure the 3197 * contains the latest status information for the 3198 * calling service. 3199 * 3200 * @return true if function succeeds. To get extended error information, call 3201 * GetLastError. Possible error codes: 3202 * <table> 3203 * <tr><th>Return code</th><th>Description</th></tr> 3204 * <tr><td>ERROR_INVALID_DATA</td><td>The specified service status structure is invalid.</td></tr> 3205 * <tr><td>ERROR_INVALID_HANDLE</td><td>The specified handle is invalid.</td></tr> 3206 * </table> 3207 */ SetServiceStatus(SERVICE_STATUS_HANDLE hServiceStatus, SERVICE_STATUS lpServiceStatus)3208 public boolean SetServiceStatus(SERVICE_STATUS_HANDLE hServiceStatus, 3209 SERVICE_STATUS lpServiceStatus); 3210 3211 /** 3212 * Creates a service object and adds it to the specified service control 3213 * manager database. 3214 * 3215 * @param hSCManager [in] A handle to the service control manager 3216 * database. This handle is returned by the 3217 * OpenSCManager function and must have the 3218 * SC_MANAGER_CREATE_SERVICE access right. For 3219 * more information, see Service Security and 3220 * Access Rights. 3221 * @param lpServiceName [in] The name of the service to install. The 3222 * maximum string length is 256 characters. The 3223 * service control manager database preserves the 3224 * case of the characters, but service name 3225 * comparisons are always case insensitive. 3226 * Forward-slash (/) and backslash (\) are not 3227 * valid service name characters. 3228 * @param lpDisplayName [in, optional] The display name to be used by 3229 * user interface programs to identify the 3230 * service. This string has a maximum length of 3231 * 256 characters. The name is case-preserved in 3232 * the service control manager. Display name 3233 * comparisons are always case-insensitive. 3234 * @param dwDesiredAccess [in] The access to the service. Before granting 3235 * the requested access, the system checks the 3236 * access token of the calling process. For a list 3237 * of values, see Service Security and Access 3238 * Rights. 3239 * @param dwServiceType [in] The service type. This parameter can be 3240 * one of the following values. 3241 * <table> 3242 * <tr><th>Value</th><th>Meaning</th></tr> 3243 * <tr><td>SERVICE_ADAPTER<br>0x00000004</td><td>Reserved.</td></tr> 3244 * <tr><td>SERVICE_FILE_SYSTEM_DRIVER<br>0x00000002</td><td>File system driver service.</td></tr> 3245 * <tr><td>SERVICE_KERNEL_DRIVER<br>0x00000001</td><td>Driver service.</td></tr> 3246 * <tr><td>SERVICE_RECOGNIZER_DRIVER<br>0x00000008</td><td>Reserved.</td></tr> 3247 * <tr><td>SERVICE_WIN32_OWN_PROCESS<br>0x00000010</td><td>Service that runs in its own process.</td></tr> 3248 * <tr><td>SERVICE_WIN32_SHARE_PROCESS<br>0x00000020</td><td>Service that shares a process with one or more other services. For more information, see Service Programs.</td></tr> 3249 * </table> 3250 * 3251 * <p>If you specify either SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS, and the service is running in the context of the LocalSystem account, you can also specify the following value.</p> 3252 * 3253 * <table> 3254 * <tr><th>Value</th><th>Meaning</th></tr> 3255 * <tr><td>SERVICE_INTERACTIVE_PROCESS<br>0x00000100</td><td>The service can interact with the desktop.</td></tr> 3256 * </table> 3257 * 3258 * @param dwStartType [in] The service start options. This parameter 3259 * can be one of the following values. 3260 * 3261 * <table> 3262 * <tr><th>Value</th><th>Meaning</th></tr> 3263 * <tr><td>SERVICE_AUTO_START<br>0x00000002</td><td>A service started automatically by the service control manager during system startup.</td></tr> 3264 * <tr><td>SERVICE_BOOT_START<br>0x00000000</td><td>A device driver started by the system loader. This value is valid only for driver services.</td></tr> 3265 * <tr><td>SERVICE_DEMAND_START<br>0x00000003</td><td>A service started by the service control manager when a process calls the StartService function.</td></tr> 3266 * <tr><td>SERVICE_DISABLED<br>0x00000004</td><td>A service that cannot be started. Attempts to start the service result in the error code ERROR_SERVICE_DISABLED.</td></tr> 3267 * <tr><td>SERVICE_SYSTEM_START<br>0x00000001</td><td>A device driver started by the IoInitSystem function. This value is valid only for driver services.</td></tr> 3268 * </table> 3269 * 3270 * @param dwErrorControl [in] The severity of the error, and action 3271 * taken, if this service fails to start. This 3272 * parameter can be one of the following values. 3273 * 3274 * <table> 3275 * <tr><th>Value</th><th>Meaning</th></tr> 3276 * <tr><td>SERVICE_ERROR_CRITICAL<br>0x00000003</td><td>The startup program logs the error in the event log, if possible. If the last-known-good configuration is being started, the startup operation fails. Otherwise, the system is restarted with the last-known good configuration.</td></tr> 3277 * <tr><td>SERVICE_ERROR_IGNORE<br>0x00000000</td><td>The startup program ignores the error and continues the startup operation.</td></tr> 3278 * <tr><td>SERVICE_ERROR_NORMAL<br>0x00000001</td><td>The startup program logs the error in the event log but continues the startup operation.</td></tr> 3279 * <tr><td>SERVICE_ERROR_SEVERE<br>0x00000002</td><td>The startup program logs the error in the event log. If the last-known-good configuration is being started, the startup operation continues. Otherwise, the system is restarted with the last-known-good configuration.</td></tr> 3280 * </table> 3281 * 3282 * @param lpBinaryPathName [in, optional] The fully qualified path to the 3283 * service binary file. If the path contains a 3284 * space, it must be quoted so that it is 3285 * correctly interpreted. For example, "d:\\my 3286 * share\\myservice.exe" should be specified as 3287 * "\"d:\\my share\\myservice.exe\"". 3288 * 3289 * <p>The path can also include arguments for an 3290 * auto-start service. For example, 3291 * "d:\\myshare\\myservice.exe arg1 arg2". These 3292 * passed to the service entry point (typically 3293 * the main function).</p> 3294 * 3295 * <p>If you specify a path on another computer, 3296 * the share must be accessible by the computer 3297 * account of the local computer because this is 3298 * the security context used in the remote call. 3299 * However, this requirement allows any potential 3300 * vulnerabilities in the remote computer to 3301 * affect the local computer. Therefore, it is 3302 * best to use a local file.</p> 3303 * 3304 * @param lpLoadOrderGroup [in, optional] The names of the load ordering 3305 * group of which this service is a member. 3306 * Specify NULL or an empty string if the service 3307 * does not belong to a group. 3308 * 3309 * <p>The startup program uses load ordering 3310 * groups to load groups of services in a 3311 * specified order with respect to the other 3312 * groups. The list of load ordering groups is 3313 * contained in the following registry value:</p> 3314 * 3315 * <p>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ServiceGroupOrder</p> 3316 * @param lpdwTagId [out, optional] A pointer to a variable that 3317 * receives a tag value that is unique in the 3318 * group specified in the lpLoadOrderGroup 3319 * parameter. Specify NULL if you are not changing 3320 * the existing tag. 3321 * 3322 * <p>You can use a tag for ordering service 3323 * startup within a load ordering group by 3324 * specifying a tag order vector in the following 3325 * registry value:</p> 3326 * 3327 * <p>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\GroupOrderList</p> 3328 * 3329 * <p>Tags are only evaluated for driver services 3330 * that have SERVICE_BOOT_START or 3331 * SERVICE_SYSTEM_START start types.</p> 3332 * @param lpDependencies [in, optional] A pointer to a double 3333 * null-terminated array of null-separated names 3334 * of services or load ordering groups that the 3335 * system must start before this service. Specify 3336 * NULL or an empty string if the service has no 3337 * dependencies. Dependency on a group means that 3338 * this service can run if at least one member of 3339 * the group is running after an attempt to start 3340 * all members of the group. 3341 * 3342 * <p>You must prefix group names with 3343 * SC_GROUP_IDENTIFIER so that they can be 3344 * distinguished from a service name, because 3345 * services and service groups share the same name 3346 * space.</p> 3347 * @param lpServiceStartName [in, optional] The name of the account under 3348 * which the service should run. If the service 3349 * type is SERVICE_WIN32_OWN_PROCESS, use an 3350 * account name in the form DomainName\UserName. 3351 * The service process will be logged on as this 3352 * user. If the account belongs to the built-in 3353 * domain, you can specify .\UserName. 3354 * 3355 * <p>If this parameter is NULL, CreateService 3356 * uses the LocalSystem account. If the service 3357 * type specifies SERVICE_INTERACTIVE_PROCESS, the 3358 * service must run in the LocalSystem account.</p> 3359 * 3360 * <p>If this parameter is NT AUTHORITY\LocalService, 3361 * CreateService uses the LocalService account. If 3362 * the parameter is NT AUTHORITY\NetworkService, 3363 * CreateService uses the NetworkService account.</p> 3364 * 3365 * <p>A shared process can run as any user.</p> 3366 * 3367 * <p>If the service type is SERVICE_KERNEL_DRIVER 3368 * or SERVICE_FILE_SYSTEM_DRIVER, the name is the 3369 * driver object name that the system uses to load 3370 * the device driver. Specify NULL if the driver 3371 * is to use a default object name created by the 3372 * I/O system.</p> 3373 * 3374 * <p>A service can be configured to use a managed 3375 * account or a virtual account. If the service is 3376 * configured to use a managed service account, 3377 * the name is the managed service account name. 3378 * If the service is configured to use a virtual 3379 * account, specify the name as NT 3380 * SERVICE\ServiceName. For more information about 3381 * managed service accounts and virtual accounts, 3382 * see the Service Accounts Step-by-Step Guide. 3383 * 3384 * <p><strong>Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP:</strong> 3385 * Managed service accounts and virtual accounts are not supported until 3386 * Windows 7 and Windows Server 2008 R2.</p> 3387 * @param lpPassword [in, optional] The password to the account name 3388 * specified by the lpServiceStartName parameter. 3389 * Specify an empty string if the account has no 3390 * password or if the service runs in the 3391 * LocalService, NetworkService, or LocalSystem 3392 * account. For more information, see Service 3393 * Record List. 3394 * 3395 * <p>If the account name specified by the 3396 * lpServiceStartName parameter is the name of a 3397 * managed service account or virtual account 3398 * name, the lpPassword parameter must be NULL.</p> 3399 * 3400 * <p>Passwords are ignored for driver services.</p> 3401 * 3402 * @return SC_HANDLE on success, NULL on error. Call GetLastError to 3403 * get extended error condition. Possible error codes: 3404 * 3405 * <table> 3406 * <tr><th>Return code</th><th>Description</th></tr> 3407 * <tr><td>ERROR_ACCESS_DENIED</td><td>The handle to the SCM database does not have the SC_MANAGER_CREATE_SERVICE access right.</td></tr> 3408 * <tr><td>ERROR_CIRCULAR_DEPENDENCY</td><td>A circular service dependency was specified.</td></tr> 3409 * <tr><td>ERROR_DUPLICATE_SERVICE_NAME</td><td>The display name already exists in the service control manager database either as a service name or as another display name.</td></tr> 3410 * <tr><td>ERROR_INVALID_HANDLE</td><td>The handle to the specified service control manager database is invalid.</td></tr> 3411 * <tr><td>ERROR_INVALID_NAME</td><td>The specified service name is invalid.</td></tr> 3412 * <tr><td>ERROR_INVALID_PARAMETER</td><td>A parameter that was specified is invalid.</td></tr> 3413 * <tr><td>ERROR_INVALID_SERVICE_ACCOUNT</td><td>The user account name specified in the lpServiceStartName parameter does not exist.</td></tr> 3414 * <tr><td>ERROR_SERVICE_EXISTS</td><td>The specified service already exists in this database.</td></tr> 3415 * <tr><td>ERROR_SERVICE_MARKED_FOR_DELETE</td><td>The specified service already exists in this database and has been marked for deletion.</td></tr> 3416 * </table> 3417 */ CreateService(SC_HANDLE hSCManager, String lpServiceName, String lpDisplayName, int dwDesiredAccess, int dwServiceType, int dwStartType, int dwErrorControl, String lpBinaryPathName, String lpLoadOrderGroup, IntByReference lpdwTagId, String lpDependencies, String lpServiceStartName, String lpPassword)3418 public SC_HANDLE CreateService(SC_HANDLE hSCManager, String lpServiceName, 3419 String lpDisplayName, int dwDesiredAccess, int dwServiceType, 3420 int dwStartType, int dwErrorControl, String lpBinaryPathName, 3421 String lpLoadOrderGroup, IntByReference lpdwTagId, 3422 String lpDependencies, String lpServiceStartName, String lpPassword); 3423 3424 /** 3425 * Marks the specified service for deletion from the service control manager database. 3426 * 3427 * @param hService [in] A handle to the service. This handle is returned by 3428 * the OpenService or CreateService function, and it must 3429 * have the DELETE access right. 3430 * 3431 * @return true if function succeeds. To get extended error information, call 3432 * GetLastError. Possible error codes: 3433 * 3434 * <table> 3435 * <tr><th>Return code</th><th>Description</th></tr> 3436 * <tr><td>ERROR_ACCESS_DENIED</td><td>The handle does not have the DELETE access right.</td></tr> 3437 * <tr><td>ERROR_INVALID_HANDLE</td><td>The specified handle is invalid.</td></tr> 3438 * <tr><td>ERROR_SERVICE_MARKED_FOR_DELETE</td><td>The specified service has already been marked for deletion.</td></tr> 3439 * </table> 3440 */ DeleteService(SC_HANDLE hService)3441 public boolean DeleteService(SC_HANDLE hService); 3442 } 3443