Java Doc for SmbFile.java in  » Groupware » hipergate » com » knowgate » jcifs » smb » Java Source Code / Java DocumentationJava Source Code and Java Documentation

 smb://[[[domain;]username[:password]@]server[:port]/[[share/[dir/]file]]][?[param=value[param2=value2[...]]]
 

 smb://storage15/public/foo.txt
 

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 Also:   java.io.File

Remember: SmbFiles are immutible and therefore the path associated with this SmbFile object will not change).

It is not possible (nor meaningful) to copy entire workgroups or servers.
Parameters:
  dest - the destination file or directory

For example, assuming the server angus resolves to the 192.168.1.15 IP address, the below URLs would result in SmbFiles that are equal.

 smb://192.168.1.15/share/DIR/foo.txt
 smb://angus/share/data/../dir/foo.txt
 

• files and directories contained within this resource if the resource is a normal disk file directory,
• all available NetBIOS workgroups or domains if this resource is the top level URL smb://,
• all servers registered as members of a NetBIOS workgroup if this resource refers to a workgroup in a smb://workgroup/ URL,
• all browseable shares of a server including printers, IPC services, or disk volumes if this resource is a server URL in the form smb://server/,
• or null if the resource cannot be resolved.

The list of SmbFiles returned by this method will be;

• files and directories contained within this resource if the resource is a normal disk file directory,
• all available NetBIOS workgroups or domains if this resource is the top level URL smb://,
• all servers registered as members of a NetBIOS workgroup if this resource refers to a workgroup in a smb://workgroup/ URL,
• all browseable shares of a server including printers, IPC services, or disk volumes if this resource is a server URL in the form smb://server/,
• or null if the resource cannot be resolved.

The wildcard expression may consist of two special meta characters in addition to the normal filename characters. The '*' character matches any number of characters in part of a name. If the expression begins with one or more '?'s then exactly that many characters will be matched whereas if it ends with '?'s it will match that many characters or less.

Wildcard expressions will not filter workgroup names or server names.

 winnt> ls c?o*
 clock.avi                  -rw--      82944 Mon Oct 14 1996 1:38 AM
 Cookies                    drw--          0 Fri Nov 13 1998 9:42 PM
 2 items in 5ms
 

Remember: SmbFiles are immutible and therefore the path associated with this SmbFile object will not change). To access the renamed file it is necessary to construct a new SmbFile.
Parameters:
  dest - An SmbFile that represents the new pathname true if the file or directory was successfully renamed
throws:
  NullPointerException - If the dest argument is null

This method does not apply to workgroups, servers, or shares.
Parameters:
  time - the create time as milliseconds since Jan 1, 1970

This method does not apply to workgroups, servers, or shares.
Parameters:
  time - the last modified time as milliseconds since Jan 1, 1970