main;]username[:password]@]server[:port]/[[share/[dir/]file]]][?[param=value[param2=value2[...]]] This example:
smb://storage15/public/foo.txt
would reference the file
foo.txt
in the share
public
on the server
storage15
. In addition to referencing files and directories, jCIFS can also address servers, and workgroups.
Important: all SMB URLs that represent workgroups, servers, shares, or directories require a trailing slash '/'.
When using the java.net.URL class with 'smb://' URLs it is necessary to first call the static jcifs.Config.registerSmbURLHandler(); method. This is required to register the SMB protocol handler.
The userinfo component of the SMB URL (domain;user:pass) must be URL encoded if it contains reserved characters. According to RFC 2396 these characters are non US-ASCII characters and most meta characters however jCIFS will work correctly with anything but '@' which is used to delimit the userinfo component from the server and '%' which is the URL escape character itself.
The server component may a traditional NetBIOS name, a DNS name, or IP address. These name resolution mechanisms and their resolution order can be changed (See Setting Name Resolution Properties). The servername and path components are not case sensitive but the domain, username, and password components are. It is also likely that properties must be specified for jcifs to function (See Setting JCIFS Properties). Here are some examples of SMB URLs with brief descriptions of what they do:
[1] This URL scheme is based largely on the SMB Filesharing URL Scheme IETF draft.
SMB URL Examples |
URL | Description |
smb://users-nyc;miallen:mypass@angus/tmp/ | This URL references a share called tmp on the server angus as user miallen who's password is mypass . |
smb://Administrator:P%40ss@msmith1/c/WINDOWS/Desktop/foo.txt | A relativly sophisticated example that references a file msmith1 's desktop as user Administrator . Notice the '@' is URL encoded with the '%40' hexcode escape. |
smb://angus/ | This references only a server. The behavior of some methods is different in this context(e.g. you cannot delete a server) however as you might expect the list method will list the available shares on this server. |
smb://myworkgroup/ | This syntactically is identical to the above example. However if myworkgroup happends to be a workgroup(which is indeed suggested by the name) the list method will return a list of servers that have registered themselves as members of myworkgroup . |
smb:// | Just as smb://server/ lists shares and smb://workgroup/ lists servers, the smb:// URL lists all available workgroups on a netbios LAN. Again, in this context many methods are not valid and return default values(e.g. isHidden and renameTo will always return false). |
smb://angus.foo.net/d/jcifs/pipes.doc | The server name may also be a DNS name as it is in this example. See Setting Name Resolution Properties for details. |
smb://192.168.1.15/ADMIN$/ | The server name may also be an IP address. See Setting Name Resolution Properties for details. |
smb://domain;username:password@server/share/path/to/file.txt | A prototypical example that uses all the fields. |
smb://myworkgroup/angus/ <-- ILLEGAL | Despite the hierarchial relationship between workgroups, servers, and filesystems this example is not valid. |
smb://server/share/path/to/dir <-- ILLEGAL | URLs that represent workgroups, servers, shares, or directories require a trailing slash '/'. |
smb://MYGROUP/?SERVER=192.168.10.15 | SMB URLs support some query string parameters. In this example the SERVER parameter is used to override the server name service lookup to contact the server 192.168.10.15 (presumably known to be a master browser) for the server list in workgroup MYGROUP . |
A second constructor argument may be specified to augment the URL for better programmatic control when processing many files under a common base. This is slightly different from the corresponding java.io.File
usage; a '/' at the beginning of the second parameter will still use the server component of the first parameter. The examples below illustrate the resulting URLs when this second contructor argument is used.
Examples Of SMB URLs When Augmented With A Second Constructor Parameter |
First Parameter | Second Parameter | Result |
smb://host/share/a/b/ | c/d/ | smb://host/share/a/b/c/d/ |
smb://host/share/foo/bar/ | /share2/zig/zag | smb://host/share2/zig/zag |
smb://host/share/foo/bar/ | ../zip/ | smb://host/share/foo/zip/ |
smb://host/share/zig/zag | smb://foo/bar/ | smb://foo/bar/ |
smb://host/share/foo/ | ../.././.././../foo/ | smb://host/foo/ |
smb://host/share/zig/zag | / | smb://host/ |
smb://server/ | ../ | smb://server/ |
smb:// | myworkgroup/ | smb://myworkgroup/ |
smb://myworkgroup/ | angus/ | smb://myworkgroup/angus/ <-- ILLEGAL (But if you first create an SmbFile with 'smb://workgroup/' and use and use it as the first parameter to a constructor that accepts it with a second String parameter jCIFS will factor out the 'workgroup'.) |
Instances of the SmbFile
class are immutable; that is, once created, the abstract pathname represented by an SmbFile object will never change.
@see java.io.File