EnumNames class method

Project: Environment Variables Unit

Unit: PJEnvVars

Class: TPJEnvironmentVars

Applies to: ~>3.0

class procedure EnumNames(Callback: TPJEnvVarsEnum; Data: Pointer);

Description

Enumerates the names of all the environment variables in the current process.

Parameters:

• Callback – Method or (for Delphi 2009 or later) anonymous procedure of type TPJEnvVarsEnum that is called once for each environment variable and is passed the the environment variable’s name and the value of the Data parameter.
• Data – Pointer passed to Callback each time it is called. The purpose of this value is user-defined and has no meaning to EnumNames.

The Callback method or (anonymous procedure) must be implemented by the caller.

Important: Environment variables should not be modified while EnumNames is executing. This is because the method takes a snap-shot of the environment variable names before it starts calling Callback. Any environment variables added or deleted while EnumNames is running will not be reflected in the enumeration and could cause obscure bugs.

Examples

Here are two implementation of methods that add the names of all environment variables to a user-provided string list.

The first implementation works with all compilers and uses a callback method. The methods we create could be part of any class, but here we assume they are part of a form class named TForm1. Implement the following methods:

procedure TForm1.EnvNameCallback(const VarName: string; Data: Pointer):
begin
  TStrings(Data).Add(VarName);
end;

procedure TForm1.EnvNamesToStrings(const Strings: TStrings);
begin
  TPJEnvironmentVars.EnumNames(EnvNameCallback, Pointer(Strings));
end;

Here our method that adds the environment variable names to a given string list is called EnvNamesToStrings and the callback method is EnvNameCallback.

In EnvNamesToStrings we call EnumNames and pass a reference to the callback to it. The interesting bit is that we pass a pointer to the string list via the Data parameter.

Now EnumNames calls EnvNamesToStrings once for each environment variable, passing the environment variable’s name in the VarName parameter and the string list pointer in the Data parameter. EnvNamesToStrings casts the Data pointer back to a TStrings object and adds the environment variable name to it.

The second example requires Delphi 2009 or later. We again implement an EnvNamesToStrings method of TForm1, but this time we dispense with the callback method and use use an anonymous procedure instead. Here’s the method:

procedure TForm1.EnvNamesToStrings(const Strings: TStrings);
begin
  TPJEnvironmentVars.EnumNames(
    procedure (const AName: string; Data: Pointer)
    begin
      SL.Add(AName);
    end,
    nil
  );
end;

Because we are using an anonymous procedure that is in the same scope as EnvNamesToStrings’s string list parameter we can access the string list object directly. This means there is no need to pass a reference to the string list to the callback via EnumName’s Data parameter, so we just pass nil.