console.CmdLink.key

console.CmdLink.key

#Overview

name: console.CmdLink.key

This variable is created as a Console Variable (cvar).

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of console.CmdLink.key is to specify the name of the pipe used for connecting to CmdLink.exe. This setting variable is primarily used in the CmdLink system, which is part of Unreal Engine’s command-line interface functionality.

The CmdLink system is implemented as a plugin in Unreal Engine, specifically in the CmdLinkServer module. This module relies on the console.CmdLink.key variable to establish a named pipe for communication between the engine and external command-line tools.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined using FAutoConsoleVariableRef, which allows it to be changed at runtime through console commands or configuration files.

The console.CmdLink.key variable interacts closely with the CLIPipeKey variable. They share the same value, with CLIPipeKey serving as the actual storage for the key value within the C++ code.

Developers should be aware of the following when using this variable:

  1. The default value is “None”, which results in a default pipe name of “UnrealEngine-CLI”.
  2. When set to a non-“None” value, the pipe name becomes “UnrealEngine-CLI-[Key]”.
  3. Changing this value at runtime will trigger the OnCmdLinkKeyChanged function, which updates the CmdLink server accordingly.

Best practices for using this variable include:

  1. Use unique keys when running multiple instances of the engine to avoid pipe name conflicts.
  2. Be consistent with key usage between the engine and any external tools connecting via CmdLink.
  3. Consider security implications when setting custom keys, as they affect the accessibility of the command-line interface.

Regarding the associated variable CLIPipeKey:

The purpose of CLIPipeKey is to store the actual value of the console.CmdLink.key within the C++ code. It’s an internal representation of the console variable.

CLIPipeKey is used directly in the CmdLinkServer module to construct the pipe name for communication. It’s also used in the main function of the CmdLink program to ensure the client connects to the correct pipe.

The value of CLIPipeKey is set indirectly through the console.CmdLink.key console variable. When the console variable changes, the OnCmdLinkKeyChanged function updates the server with the new CLIPipeKey value.

CLIPipeKey interacts primarily with the console.CmdLink.key variable, serving as its storage and being used in pipe name construction.

Developers should be aware that CLIPipeKey is an internal variable and should not be modified directly. Instead, they should use the console.CmdLink.key console variable to change its value.

Best practices for CLIPipeKey include:

  1. Treat it as a read-only variable in most contexts.
  2. Use it consistently when constructing pipe names throughout the codebase.
  3. Ensure that any code depending on CLIPipeKey can handle potential runtime changes to its value.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Plugins/CmdLinkServer/Source/CmdLinkServer/Private/CmdLinkServer.cpp:23

Scope (from outer to inner):

file
namespace    UE::CmdLink

Source code excerpt:

	void OnCmdLinkKeyChanged(IConsoleVariable* Var);
	FAutoConsoleVariableRef CVarCmdLinkKey(
		TEXT("console.CmdLink.key"),
		CLIPipeKey,
		TEXT("Changes the name of the pipe used for a connection to CmdLink.exe"),
		FConsoleVariableDelegate::CreateStatic(OnCmdLinkKeyChanged),
		ECVF_Default);

	void OnCmdLinkEnabledChanged(IConsoleVariable* Var)

#Associated Variable and Callsites

This variable is associated with another variable named CLIPipeKey. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Plugins/CmdLinkServer/Source/CmdLinkServer/Private/CmdLinkServer.cpp:20

Scope (from outer to inner):

file
namespace    UE::CmdLink

Source code excerpt:

		ECVF_Default);

	FString CLIPipeKey = TEXT("None");
	void OnCmdLinkKeyChanged(IConsoleVariable* Var);
	FAutoConsoleVariableRef CVarCmdLinkKey(
		TEXT("console.CmdLink.key"),
		CLIPipeKey,
		TEXT("Changes the name of the pipe used for a connection to CmdLink.exe"),
		FConsoleVariableDelegate::CreateStatic(OnCmdLinkKeyChanged),
		ECVF_Default);

	void OnCmdLinkEnabledChanged(IConsoleVariable* Var)
	{

#Loc: <Workspace>/Engine/Plugins/CmdLinkServer/Source/CmdLinkServer/Private/CmdLinkServer.cpp:48

Scope (from outer to inner):

file
namespace    UE::CmdLink
function     void OnCmdLinkKeyChanged

Source code excerpt:

		if (FCmdLinkServerModule* Server = FCmdLinkServerModule::Get())
		{
			Server->OnKeyChanged(CLIPipeKey);
		}
	}
	
	extern UNREALED_API void(*GBeginAsyncCommand)(const FString&, const TArray<FString>&);
	extern UNREALED_API void(*GEndAsyncCommand)(const FString&, const TArray<FString>&);
}

#Loc: <Workspace>/Engine/Plugins/CmdLinkServer/Source/CmdLinkServer/Private/CmdLinkServer.cpp:337

Scope (from outer to inner):

file
function     void FCmdLinkServerModule::InitStateMachine
lambda-function

Source code excerpt:

	{
		// if there's a key specified, include it in the name
		const FString PipeName = UE::CmdLink::CLIPipeKey == TEXT("None") ? TEXT("UnrealEngine-CLI") : TEXT("UnrealEngine-CLI-") + UE::CmdLink::CLIPipeKey;
		// Create the output pipe as a server...
		if (!NamedPipe.Create(FString::Printf(TEXT("\\\\.\\pipe\\%s"), *PipeName), true, true))
		{
			return SLEEP_FOR_RECONNECT; // wait 5 seconds and try again
		}
		if (!NamedPipe.OpenConnection())

#Loc: <Workspace>/Engine/Source/Programs/CmdLink/Private/CmdLink.cpp:34

Scope (from outer to inner):

file
function     int32 main

Source code excerpt:

int32 main(int32 ArgC, ANSICHAR* ArgV[])
{
	FString CLIPipeKey;
	if (ArgC >= 2 && FParse::Value(StringCast<TCHAR>(ArgV[1]).Get(),TEXT("--LinkKey="),CLIPipeKey))
	{
		// don't send this argument to the server. it's meant for Client only
		--ArgC;
		++ArgV;
	}

#Loc: <Workspace>/Engine/Source/Programs/CmdLink/Private/CmdLink.cpp:52

Scope (from outer to inner):

file
function     int32 main

Source code excerpt:

	// 2. char[responseLen] response (includes null terminating character)
	
	const FString PipeName = CLIPipeKey.IsEmpty() ? TEXT("UnrealEngine-CLI") : TEXT("UnrealEngine-CLI-") + CLIPipeKey;
	FPlatformNamedPipe NamedPipe;
	TRY(NamedPipe.Create(FString::Printf(TEXT("\\\\.\\pipe\\%s"), *PipeName), false, false), CONNECT_FAILED);

	// Send ArgC
	TRY(NamedPipe.WriteInt32(ArgC), WRITE_FAILED);