Differences

This shows you the differences between the selected revisions of the page.

2025-05-15		2025-05-16 (current)
URL (152.56.137.48) (hidden) (untrusted)		stable 6.5 released (martin)
	Line 1:		Line 1:
-	<!DOCTYPE html>	+	====== Session URL ======
-	<html lang="en">	+	On [[commandline\|command-line]] and in parameter of scripting command ''[[scriptcommand_open\|open]]'', you can specify basic session settings using session URL.
-	<head>	+
-	· <meta charset="UTF-8" />	+
-	<meta name="viewport"; content="width=device-width, initial-scale=1.0"/>	+
-	··<title>Talking Tom Clone<;/title>	+
-	<;style>	+
-	body {	+
-	font-family: Arial, sans-serif;	+
-	text-align: center;	+
-	background: #f0f0f0;	+
-	padding: 40px;	+
-	}	+

-	img {	+	In [[library\|WinSCP .NET assembly]], you can use session %%URL%% too as an alternative way to provide session options. Use method ''[[library_sessionoptions_parseurl\|SessionOptions.ParseUrl]]';'.
-	······width: 300px;	+
-	·····border-radius: 20px;	+
-	·····box-shadow: 0 4px 20px rgba(0, 0, 0, 0.3);	+
-	····}	+

-	button {	+	To ease assembling the %%URL%%, you can have WinSCP [[ui_generateurl\|generate it for you]].
-	margin-top: 20px;	+
-	·····padding: 15px 30px;	+
-	font-size: 20px;	+
-	background-color: #4CAF50;	+
-	color: white;	+
-	······border: none;	+
-	border-radius: 10px;	+
-	cursor: pointer;	+
-	transition: background 0.3s;	+
-	}	+

-	····button:hover {	+	===== [[syntax]] Syntax =====
-	·····background-color: #45a049;	+
-	····}	+

-	#status {	+	<code>
-	margin-top: 15px;	+	<protocol> :// [ <username> [ : <password> ] [ ; <advanced> ] @ ] <host> [ : <port> ] /
-	font-weight: bold;	+	</code>
-	}	+
-	··</style>	+
-	</head>	+
-	<body>	+
-	<h1>Talking Tom Clone</h1>	+
-	<;img src="https://freeimage.host/images/2024/05/15/3rFyMyF.png" alt="Talking Tom" />	+
-	·<br>	+
-	<button id="toggleButton">Play</button>	+
-	<div id="status">Press play to start listening</div>	+

-	··<script>	+	===== [[elements]] Elements =====
-	const button = document.getElementById("toggleButton");	+
-	const statusText = document.getElementById("status");	+
-	let listening = false;	+
-	let recognition;	+

-	if ("webkitSpeechRecognition" in window) {	+	The only mandatory part is ''host''. The ==host== can either be a host name (such as ';'example.com';'), an IPv4 address (such as ''127.0.0.1'') or an IPv6 address surrounded by square brackets (such as ';'[2001:db8:85a3:8d3:1319:8a2e:370:7348]'').
-	······recognition = new webkitSpeechRecognition();	+
-	······recognition.continuous = false;	+
-	······recognition.lang = "en-US";	+
-	······recognition.interimResults = false;	+

-	······recognition.onstart = () => {	+	You should also always explicitly specify a protocol (''[[sftp]]'', ''[[ftp]]'', ''[[scp]]'', ''[[s3]]'', for [[ftps\|FTP over implicit TLS/SSL]] use ''ftps'', for [[ftps\|FTP over explicit TLS/SSL]] use ''ftpes'', for [[WebDAV]] use ''http'', for WebDAV over TLS/SSL use ''https''). ((Protocol is ''sftp'' by default, but the default can be changed.)) For all protocols [[integration_url#winscp\|WinSCP-specific alternative]] is supported, with ''winscp-''; prefix. URLs with ''%%http[s]%%'' protocol, but with known S3 API hostnames,((''s3.amazonaws.com'', ''digitaloceanspaces.com'', ''storage.googleapis.com'', ''r2.cloudflarestorage.com'';, ''compat.objectstorage.*.oraclecloud.com'')) are recognized as S3, not as WebDAV.
-	·······statusText.textContent = "Listening...";	+
-	·····};	+

-	······recognition.onresult = (event) => {	+	Most %%URL%%'s will include also ''username''.
-	const transcript = event.results[0][0].transcript;	+
-	········speak(transcript);	+
-	};	+

-	······recognition.onerror = (event) => {	+	The ''port'' needs to be specified only, when it differs from the default port for the protocol (22 for ''sftp''/''scp'', 21 for ''ftp'' and ''ftpes'';, 990 for implicit '';ftps'', 80 for ''http''; and 443 for ''https'' and ''s3'').
-	·······console.error("Speech recognition error:", event.error);	+
-	········statusText.textContent = "Error occurred: " + event.error;	+
-	·····};	+

-	······recognition.onend = () => {	+	===== [[advanced]] Advanced Settings =====
-	········if (listening) {	+
-	recognition.start(); // auto-restart	+
-	}	+
-	};	+
-	} else {	+
-	alert("Speech recognition not supported in this browser.");	+
-	}	+

-	····function speak(text) {	+	A session %%URL%% can optionally set any advanced session settings using a syntax based on [[rawsettings\|raw site settings]].
-	·····const utterance = new SpeechSynthesisUtterance(text);	+
-	·····speechSynthesis.speak(utterance);	+	Providing advanced settings in the session %%URL%% is mainly useful, if you need to provide all session settings using %%URL%% only, such as using [[integration_url\|a hyperlink on a web page]]; or when you want to serialize all session settings into a single "connection string", such as when passing the current setting settings to a WinSCP [[extension]].
-	·····statusText.textContent = "Repeating: " + text;	+
-	···}	+	A syntax to serialize raw site settings is '';x-name1=value1;x-name2=value2'' (inserted after username and password).
		+
		+	For example to use an HTTP proxy server ''proxy'', use the following %%URL%%: \\ ''%%sftp://username:password;x-proxymethod=3;x-proxyhost=proxy@example.com/%%''
		+
		+	To have WinSCP generate a session %%URL%% with the advanced settings, check //Advanced settings// on [[ui_generateurl\|Generate session URL/code]] dialog. To serialize all session settings for a WinSCP extension, use ''!E'' [[custom_command#patterns\|pattern]].
		+
		+	When [[integration_url\|using the URL in webbrowser]], note that this syntax is not compatible with Chrome M130 and newer (and Edge based on it), as Chrome re-encodes the ==semicolons==. Workaround is to drop the ''%%//%%'' separator after the protocol from the URL. Such format is acceptable for WinSCP and prevents Chrome from reinterpreting the URL.
		+
		+	===== [[hostkey]] SSH Host Key Fingerprint =====
		+
		+	There's a special syntax to include an expected [[ssh_verifying_the_host_key\|SSH host key fingerprint]] in SFTP/SCP %%URL%% among advanced site settings: ''fingerprint=<fingerprint>''.
		+
		+	For security reasons, fingerprint provided in session %%URL%% does not override any fingerprint already cached on the machine. This for instance differs from behavior, when fingerprint is provided using ''[[scriptcommand_open#hostkey\|-hostkey]]'' switch of ''[[scriptcommand_open\|open]]'' command in scripting.
		+
		+	Format of the fingerprint for %%URL%%((Fingerprint format for %%URL%% is based on [[https://datatracker.ietf.org/doc/html/draft-ietf-secsh-scp-sftp-ssh-uri-04\|draft-ietf-secsh-scp-sftp-ssh-uri]].)) somewhat differs from format used in other WinSCP features (';'[[scriptcommand_open#hostkey\|-hostkey]]'' switch of ''[[scriptcommand_open\|open]]'' command in scripting for instance). To convert WinSCP fingerprint format to %%URL%% format:
		+
		+	·- Drop bit count part (the number after ''ssh-rsa'', ''ssh-dss'', etc., typically ''2048'' or ''1024'');
		+	- Replace the remaining space with a dash sign (''-'').
		+	- Pluses (';'+'') and slashes (''/'') in SHA-256 hash need to be [[#special\|encoded]] or replaced with dashes (''-'') and underscores (''_'') respectively.((In case you are still using MD5 fingerprints, replace all colons ('':'') with a dash sign (''-'') too. Though you should switch to SHA-256 fingerprints.))
		+
		+	For example WinSCP fingerprint ''ssh-rsa 2048 2EP3avJqmpRtSRaUIqwrzavm15vssrhHxJWh9mBaz8M'' converts to ''ssh-rsa-2EP3avJqmpRtSRaUIqwrzavm15vssrhHxJWh9mBaz8M''.
		+
		+	===== [[special]] Special Characters =====
		+
		+	Special characters (like ''@'' in username, see example below) have to be encoded using ''%XX'' syntax, where ''XX'' is hexadecimal UTF-8 code.((For multi-byte codes, use ''%'' before every byte, for instance to represent pound-sign ''£'' use ''%C2%A3''.))
		+
		+	Common special characters are:
		+
		+	* space: ''%20''; or ''+''
		+	· * ';'#'': ''%23'' (number sign/hash)
		+	·* ''%'': ''%25'' (percent sign)
		+	* ''+'': ''%2B'' (plus sign)
		+	* ''/'': ''%2F'' (slash)
		+	* ''@'': ''%40'' (at sign)
		+	* '':'': ''%3A'' (colon)
		+	* '';'': ''%3B'' (semicolon)
		+
		+	Note that when specifying session %%URL%% on [[commandline\|command-line]], you cannot use characters that have special meaning on Windows command-line, just as with any other command-line argument. Such characters include ''&'' (ampersand), ''\|'' (pipe), ''<'' (less-than sign), ''>'' (greater-than sign), ''%%"%%'' (double-quote). To escape these characters, you can wrap whole session %%URL%% to double-quotes (''%%"%%'') or encode the characters as shown above.
		+
		+	Further, in Windows batch files, ''%'' (percent sign) needs to be doubled to be used correctly, even when the sign is itself used to encode other special characters. For example, to use ''@'' in a username, specify ''<nowiki>%%40</nowiki>''. Other programming and scripting languages have other special characters that need to be escaped using a construct of the respective language (for example ''$'' in PowerShell has to be escaped as ''`$'').
		+
		+	You can have WinSCP [[ui_generateurl\|generate correct URL]] for all kinds of uses (command-line, script or batch file).
		+
		+	To avoid having to URL-encode the credentials, particularly when sourcing them from a variable, you can use ''-username'' and ''-password'' switches of the [[scriptcommand_open#username\|''open'' command]] or [[commandline#username\|WinSCP command-line]].
		+
		+	===== Examples =====
		+
		+
		+	sftp://martin:mypassword@example.com/
		+	sftp://root@example.com:2222/
		+	sftp://martin%40example.com:4pRte!ai%253@example.com/
		+	ftp://127.0.0.1:2121/
		+	ftp://[2001:db8:85a3:8d3:1319:8a2e:370:7348]:2121/
		+	sftp://martin;fingerprint=ssh-rsa-2EP3avJqmpRtSRaUIqwrzavm15vssrhHxJWh9mBaz8M=@example.com/
		+	http://martin@example.com/dav/
		+
		+
		+	===== [[file]] Directory or File URL =====
		+
		+	A [[commandline#session\|URL specified on command-line]] can include an initial remote path (the path has to end with a slash): \\
		+	''%%sftp://username@example.com/remote/path/%%''
		+
		+	You can also include a file path into the URL: \\
		+	''sftp://username@example.com/remote/path/file.txt''
		+
		+	By default, it will initiate the file [[task_download#url\|download]]. When combined with [[commandline#operations\|''/browse'' switch]], the file will instead be selected in a [[ui_file_panel\|file panel]].
		+
		+	===== [[other]] Other Uses =====
		+
		+	You can also [[ui_login#pasting\|paste the session URL on Login dialog]] or [[clipboard#url\|main window]] or even Windows File Explorer or web browser (if WinSCP is [[integration_url\|registered]] to handle file transfer protocol %%URL%% addresses). You can use the session URL as a way to [[config#transfer\|transfer site settings]].
		+
		+	You can use [[custom_command\|custom command]] patterns ''!E'' or ''!S'' to pass a session %%URL%% to other processes.

-	button.onclick = () => {
-	if (!listening) {
-	recognition.start();
-	listening = true;
-	button.textContent = "Stop";
-	} else {
-	recognition.stop();
-	listening = false;
-	button.textContent = "Play";
-	statusText.textContent = "Stopped listening";
-	}
-	};
-	</script>
-	</body>
-	</html>

Differences

Documentation

Support

Associations

Follow Us