System.Security.Permissions.EnvironmentPermission Class

Assembly: Mscorlib.dll
Namespace: System.Security.Permissions
Summary
Controls access to system and user environment variables. This class cannot be inherited.
C# Syntax:
[Serializable]
public sealed class EnvironmentPermission : CodeAccessPermission, IUnrestrictedPermission
Remarks
Environment variable names are designated by one or more case-insensitive name lists separated by semicolons, with separate lists for read and write access to the named variables. Write access includes the ability to create and delete environment variables as well as to change existing values.
See also:
System.Security.Permissions Namespace See also:
MSDN: permissions | MSDN: requestingpermissions | EnvironmentPermissionAttribute | EnvironmentPermissionAccess

System.Security.Permissions.EnvironmentPermission Member List:

Public Constructors
ctor #1 Overloaded:
.ctor(PermissionState state)

Initializes a new instance of the EnvironmentPermission class with either restricted or unrestricted permission as specified.
ctor #2 Overloaded:
.ctor(EnvironmentPermissionAccess flag, string pathList)

Initializes a new instance of the EnvironmentPermission class with the specified access to the specified environment variables.
Public Methods
AddPathList Adds access for the specified environment variables to the existing state of the permission.
Assert
(inherited from System.Security.CodeAccessPermission)
See base class member description: System.Security.CodeAccessPermission.Assert


Asserts that calling code can access the resource identified by the current permission through the code that calls this method, even if callers higher in the stack have not been granted permission to access the resource.
Copy Overridden:
Creates and returns an identical copy of the current permission.
Demand
(inherited from System.Security.CodeAccessPermission)
See base class member description: System.Security.CodeAccessPermission.Demand


Forces a SecurityException at run time if all callers higher in the call stack have not been granted the permission specified by the current instance.
Deny
(inherited from System.Security.CodeAccessPermission)
See base class member description: System.Security.CodeAccessPermission.Deny


Prevents callers higher in the call stack from using the code that calls this method to access the resource specified by the current instance.
Equals
(inherited from System.Object)
See base class member description: System.Object.Equals

Derived from System.Object, the primary base class for all objects.
FromXml Overridden:
Reconstructs a permission with a specified state from an XML encoding.
GetHashCode
(inherited from System.Object)
See base class member description: System.Object.GetHashCode

Derived from System.Object, the primary base class for all objects.
GetPathList Gets all environment variables with the specified EnvironmentPermissionAccess.
GetType
(inherited from System.Object)
See base class member description: System.Object.GetType

Derived from System.Object, the primary base class for all objects.
Intersect Overridden:
Creates and returns a permission that is the intersection of the current permission and the specified permission.
IsSubsetOf Overridden:
Determines whether the current permission is a subset of the specified permission.
IsUnrestricted Returns a value indicating whether the current permission is unrestricted.
PermitOnly
(inherited from System.Security.CodeAccessPermission)
See base class member description: System.Security.CodeAccessPermission.PermitOnly


Prevents callers higher in the call stack from using the code that calls this method to access all resources except for the resource specified by the current instance.
SetPathList Sets the specified access to the specified environment variables to the existing state of the permission.
ToString
(inherited from System.Security.CodeAccessPermission)
See base class member description: System.Security.CodeAccessPermission.ToString


Creates and returns a string representation of the current permission object.
ToXml Overridden:
Creates an XML encoding of the permission and its current state.
Union Overridden:
Creates a permission that is the union of the current permission and the specified permission.
Protected Methods
Finalize
(inherited from System.Object)
See base class member description: System.Object.Finalize

Derived from System.Object, the primary base class for all objects.
MemberwiseClone
(inherited from System.Object)
See base class member description: System.Object.MemberwiseClone

Derived from System.Object, the primary base class for all objects.

Hierarchy:


System.Security.Permissions.EnvironmentPermission Member Details

Overloaded ctor #1
Summary
Initializes a new instance of the EnvironmentPermission class with either restricted or unrestricted permission as specified.
C# Syntax:
public EnvironmentPermission(
   PermissionState state
);
Parameters:

state

One of the PermissionState values.

Exceptions
Exception Type Condition
ArgumentException The state parameter is not a valid value of PermissionState.
Remarks
Creates either fully restricted (None) or Unrestricted access to all environment variables.

Return to top


Overloaded ctor #2
Summary
Initializes a new instance of the EnvironmentPermission class with the specified access to the specified environment variables.
C# Syntax:
public EnvironmentPermission(EnvironmentPermission(
   EnvironmentPermissionAccess flag,
   string pathList
);
Parameters:

flag

One of the EnvironmentPermissionAccess values.

pathList

A list of environment variables (semicolon-separated) to which access is granted.

Exceptions
Exception Type Condition
ArgumentNullException The pathList parameter is null.
ArgumentException The flag parameter is not a valid value of EnvironmentPermissionAccess.
Remarks
This constructor allows only one of the EnvironmentPermissionAccess values to be specified. This access applies to all listed environment variables. Use EnvironmentPermission.AddPathList to define complex permissions.

Return to top


Method: AddPathList(
   EnvironmentPermissionAccess flag,
   string pathList
)
Summary
Adds access for the specified environment variables to the existing state of the permission.
C# Syntax:
public void AddPathList(
   EnvironmentPermissionAccess flag,
   string pathList
);
Parameters:

flag

One of the EnvironmentPermissionAccess values.

pathList

A list of environment variables (semicolon-separated).

Exceptions
Exception Type Condition
ArgumentNullException The pathList parameter is null.
ArgumentException The flag parameter is not a valid value of EnvironmentPermissionAccess.
Remarks
Use this method to modify environment variable access by adding to the state of the current permission.

Return to top


Method: Assert()
Inherited
See base class member description: System.Security.CodeAccessPermission.Assert

Summary
Asserts that calling code can access the resource identified by the current permission through the code that calls this method, even if callers higher in the stack have not been granted permission to access the resource.
C# Syntax:
public void Assert();
Exceptions
Exception Type Condition
SecurityException The calling code does not have SecurityPermissionFlag.Assertion.

-or-

There is already an active CodeAccessPermission.Assert for the current frame.

Implements:
IStackWalk.Assert
Remarks
The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. Calling CodeAccessPermission.Assert prevents a stack walk originating lower in the call stack from proceeding up the call stack beyond the code that calls this method. Therefore, even if callers higher on the call stack do not have the requisite permissions to access a resource, they can still access it through the code that calls this method on the necessary permission. An assertion is effective only if the code that calls CodeAccessPermission.Assert passes the security check for the permission that it is asserting.

The call to CodeAccessPermission.Assert is effective until the calling code returns to its caller. Only one CodeAccessPermission.Assert can be active on a frame. An attempt to call CodeAccessPermission.Assert when an active CodeAccessPermission.Assert exists on the frame results in a SecurityException. Call CodeAccessPermission.RevertAssert or CodeAccessPermission.RevertAll to remove an active CodeAccessPermission.Assert.

CodeAccessPermission.Assert is ignored for a permission not granted because a demand for that permission will not succeed. However, if code lower on the call stack calls CodeAccessPermission.Demand for that permission, a SecurityException is thrown when the stack walk reaches the code that tried to call CodeAccessPermission.Assert. This happens because the code that called CodeAccessPermission.Assert has not been granted the permission, even though it tried to CodeAccessPermission.Assert it.

Because calling CodeAccessPermission.Assert removes the requirement that all code in the call chain must be granted permission to access the specified resource, it can open up security vulnerabilities if used incorrectly or inappropriately. Therefore, it should be used with great caution.

Notes to inheritors: You cannot override this method.
.NET Framework Security:
SecurityPermission for the ability to call CodeAccessPermission.Assert. Associated enumeration: SecurityPermissionFlag.Assertion
See also:
MSDN: assert | MSDN: overridingsecuritychecks

Return to top


Overridden Method: Copy()
Summary
Creates and returns an identical copy of the current permission.
C# Syntax:
public override IPermission Copy();
Return Value:
A copy of the current permission.
Implements:
IPermission.Copy
Remarks
A copy of a permission represents the same access to resources as the original permission.

Return to top


Method: Demand()
Inherited
See base class member description: System.Security.CodeAccessPermission.Demand

Summary
Forces a SecurityException at run time if all callers higher in the call stack have not been granted the permission specified by the current instance.
C# Syntax:
public void Demand();
Exceptions
Exception Type Condition
SecurityException A caller higher in the call stack does not have the permission specified by the current instance.

-or-

A caller higher in the call stack has called CodeAccessPermission.Deny on the current permission object.

Implements:
IPermission.Demand
Implements:
IStackWalk.Demand
Remarks
This method is typically used by secure libraries to ensure that callers have permission to access a resource. For example, a file class in a secure class library calls CodeAccessPermission.Demand for the necessary FileIOPermission before performing a file operation requested by the caller.

The permissions of the code that calls this method are not examined; the check begins from the immediate caller of that code and proceeds up the stack. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack. CodeAccessPermission.Demand succeeds only if no SecurityException is raised.



Notes to inheritors: You cannot override this method.
See also:
MSDN: makingsecuritydemands

Return to top


Method: Deny()
Inherited
See base class member description: System.Security.CodeAccessPermission.Deny

Summary
Prevents callers higher in the call stack from using the code that calls this method to access the resource specified by the current instance.
C# Syntax:
public void Deny();
Exceptions
Exception Type Condition
SecurityException There is already an active CodeAccessPermission.Deny for the current frame.
Implements:
IStackWalk.Deny
Remarks
This method prevents callers higher in the call stack from accessing the protected resource through the code that calls this method, even if those callers have been granted permission to access it. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack.

CodeAccessPermission.Deny can limit the liability of the programmer or prevent accidental security vulnerabilities because it prevents the method that calls CodeAccessPermission.Deny from being used to access the resource protected by the denied permission. If a method calls CodeAccessPermission.Deny on a permission, and if a CodeAccessPermission.Demand for that permission is invoked by a caller lower in the call stack, that security check will fail when it reaches the CodeAccessPermission.Deny.

The call to CodeAccessPermission.Deny is effective until the calling code returns to its caller. Only one CodeAccessPermission.Deny can be active on a frame. An attempt to call CodeAccessPermission.Deny when an active CodeAccessPermission.Deny exists on the frame results in a SecurityException. Call CodeAccessPermission.RevertDeny or CodeAccessPermission.RevertAll to remove an active CodeAccessPermission.Deny. CodeAccessPermission.Deny is ignored for a permission not granted because a demand for that permission will not succeed.



Notes to inheritors: You cannot override this method.
See also:
MSDN: deny | MSDN: overridingsecuritychecks

Return to top


Method: Equals(
   object obj
)
Inherited
See base class member description: System.Object.Equals
C# Syntax:
public virtual bool Equals(
   object obj
);

For more information on members inherited from System.Object click on the link above.

Return to top


Method: Finalize()
Inherited
See base class member description: System.Object.Finalize
C# Syntax:
~EnvironmentPermission();

For more information on members inherited from System.Object click on the link above.

Return to top


Overridden Method: FromXml(
   SecurityElement esd
)
Summary
Reconstructs a permission with a specified state from an XML encoding.
C# Syntax:
public override void FromXml(
   SecurityElement esd
);
Parameters:

esd

The XML encoding to use to reconstruct the permission.

Exceptions
Exception Type Condition
ArgumentNullException The esd parameter is null.
ArgumentException The esd parameter is not a valid permission element.

-or-

The esd parameter's version number is not valid.

Implements:
ISecurityEncodable.FromXml

Return to top


Method: GetHashCode()
Inherited
See base class member description: System.Object.GetHashCode
C# Syntax:
public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: GetPathList(
   EnvironmentPermissionAccess flag
)
Summary
Gets all environment variables with the specified EnvironmentPermissionAccess.
C# Syntax:
public string GetPathList(
   EnvironmentPermissionAccess flag
);
Parameters:

flag

One of the EnvironmentPermissionAccess values.

Return Value:
A list of environment variables (semicolon-separated) for the selected flag.
Exceptions
Exception Type Condition
ArgumentException The flag parameter is not a valid value of EnvironmentPermissionAccess.
Remarks
Use this method to get the state of the current permission. To get both Read and Write access states requires two calls to this method.

Return to top


Method: GetType()
Inherited
See base class member description: System.Object.GetType
C# Syntax:
public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top


Overridden Method: Intersect(
   IPermission target
)
Summary
Creates and returns a permission that is the intersection of the current permission and the specified permission.
C# Syntax:
public override IPermission Intersect(
   IPermission target
);
Parameters:

target

A permission to intersect with the current permission. It must be of the same type as the current permission.

Return Value:
A new permission that represents the intersection of the current permission and the specified permission. This new permission is null if the intersection is empty.
Exceptions
Exception Type Condition
ArgumentException The target parameter is not null and is not of the same type as the current permission.
Implements:
IPermission.Intersect
Remarks
The intersection of two permissions is a permission that describes the state they both describe in common. Only a demand that passes both original permissions will pass the intersection.

Return to top


Overridden Method: IsSubsetOf(
   IPermission target
)
Summary
Determines whether the current permission is a subset of the specified permission.
C# Syntax:
public override bool IsSubsetOf(
   IPermission target
);
Parameters:

target

A permission that is to be tested for the subset relationship. This permission must be of the same type as the current permission.

Return Value:
true if the current permission is a subset of the specified permission; otherwise, false.
Exceptions
Exception Type Condition
ArgumentException The target parameter is not null and is not of the same type as the current permission.
Implements:
IPermission.IsSubsetOf
Remarks
The current permission is a subset of the specified permission if the current permission specifies a state that is wholly contained by the specified permission. For example, a permission that represents access to C:\example.txt is a subset of a permission that represents access to C:\. If this method returns true, the current permission represents no more access to the protected resource than does the specified permission.

Return to top


Method: IsUnrestricted()
Summary
Returns a value indicating whether the current permission is unrestricted.
C# Syntax:
public bool IsUnrestricted();
Return Value:
true if the current permission is unrestricted; otherwise, false.
Implements:
IUnrestrictedPermission.IsUnrestricted
Remarks
An unrestricted permission represents the union of all possible states of the permission.

Return to top


Method: MemberwiseClone()
Inherited
See base class member description: System.Object.MemberwiseClone
C# Syntax:
protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: PermitOnly()
Inherited
See base class member description: System.Security.CodeAccessPermission.PermitOnly

Summary
Prevents callers higher in the call stack from using the code that calls this method to access all resources except for the resource specified by the current instance.
C# Syntax:
public void PermitOnly();
Exceptions
Exception Type Condition
SecurityException There is already an active CodeAccessPermission.PermitOnly for the current frame.
Implements:
IStackWalk.PermitOnly
Remarks
CodeAccessPermission.PermitOnly is similar to CodeAccessPermission.Deny, in that both cause stack walks to fail when they would otherwise succeed. The difference is that CodeAccessPermission.Deny specifies permissions that will cause the stack walk to fail, but CodeAccessPermission.PermitOnly specifies the only permissions that do not cause the stack walk to fail.

Call this method to ensure that your code can be used to access only the specified resources. The call to CodeAccessPermission.PermitOnly is effective until the calling code returns to its caller. Only one CodeAccessPermission.PermitOnly can be active on a frame. An attempt to call CodeAccessPermission.PermitOnly when an active CodeAccessPermission.PermitOnly exists on the frame results in a SecurityException. Call CodeAccessPermission.RevertPermitOnly or CodeAccessPermission.RevertAll to remove an active CodeAccessPermission.PermitOnly.

CodeAccessPermission.PermitOnly is ignored for a permission not granted because a demand for that permission will not succeed. However, if code lower on the call stack later calls CodeAccessPermission.Demand for that permission, a SecurityException is thrown when the stack walk reaches the code that tried to call CodeAccessPermission.PermitOnly. This is because the code that called CodeAccessPermission.PermitOnly has not been granted the permission, even though it called CodeAccessPermission.PermitOnly for that permission. The call stack is typically represented as growing down, so that methods higher in the call stack call methods lower in the call stack.



Notes to inheritors: You cannot override this method.
See also:
MSDN: permitonly | MSDN: overridingsecuritychecks

Return to top


Method: SetPathList(
   EnvironmentPermissionAccess flag,
   string pathList
)
Summary
Sets the specified access to the specified environment variables to the existing state of the permission.
C# Syntax:
public void SetPathList(
   EnvironmentPermissionAccess flag,
   string pathList
);
Parameters:

flag

One of the EnvironmentPermissionAccess values.

pathList

A list of environment variables (semicolon-separated).

Exceptions
Exception Type Condition
ArgumentNullException The pathList parameter is null.
ArgumentException The flag parameter is not a valid value of EnvironmentPermissionAccess.
Remarks
The previous state of the current permission is overwritten.

Return to top


Method: ToString()
Inherited
See base class member description: System.Security.CodeAccessPermission.ToString

Summary
Creates and returns a string representation of the current permission object.
C# Syntax:
public override string ToString();
Return Value:
A string representation of the current permission object.
Remarks
This method is useful in debugging when you need to display the permission as a string.

Return to top


Overridden Method: ToXml()
Summary
Creates an XML encoding of the permission and its current state.
C# Syntax:
public override SecurityElement ToXml();
Return Value:
An XML encoding of the permission, including any state information.
Implements:
ISecurityEncodable.ToXml

Return to top


Overridden Method: Union(
   IPermission other
)
Summary
Creates a permission that is the union of the current permission and the specified permission.
C# Syntax:
public override IPermission Union(
   IPermission other
);
Parameters:

other

A permission to combine with the current permission. It must be of the same type as the current permission.

Return Value:
A new permission that represents the union of the current permission and the specified permission.
Exceptions
Exception Type Condition
ArgumentException The other parameter is not null and is not of the same type as the current permission.
Implements:
IPermission.Union
Remarks
The result of a call to EnvironmentPermission.Union is a permission that represents all the states represented by both the current permission and the specified permission. Any demand that passes either permission passes their union.

Return to top


Top of page

Copyright (c) 2002 Microsoft Corporation. All rights reserved.