jcifs.smb
Class SmbFile

java.lang.Object
  |
  +--java.net.URLConnection
        |
        +--jcifs.smb.SmbFile
Direct Known Subclasses:
SmbNamedPipe

public class SmbFile
extends java.net.URLConnection

This class represents a resource on an SMB network. Mainly these resources are files and directories however an SmbFile may also refer to servers and workgroups. If the resource is a file or directory the methods of SmbFile follow the behavior of the well known File class. One fundamental difference is the usage of a URL scheme* to specify the target file or directory. SmbFile URLs have the following syntax:

     smb://[[[domain;]username[:password]@]server[:port]/[[share/[dir/]file]]]
 
This example:
     smb://storage15/public/foo.txt
 
would referece 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.

Please note that beginning with jcifs-0.7.0b4 all SMB URLs that represent workgroups, servers, shares, or directories require a trailing slash '/'. This will break older code and you may or may not get an exception. For example:

smb://server/share/path/to/dir/  <-- GOOD

smb://server/share/path/to/dir   <-- BAD
To assist you with this, the getName method will now include a slash '/' after the name if the URL refers to a directory (e.g. 'dir/').

When using the java.net.URL class with 'smb://' URLs it is necessary to first call the static jcifs.Config.registerSmbURLHandler(); method (prior to jcifs-0.7.0b12 it was Class.forName( "jcifs.Config" ); but this is no longer necessary).

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.

When used in conjunction with the list method, this functionality can be usefull for network diagnostics tools or "Network Neighborhood" like functionality. 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:

* This URL scheme is based largely on the SMB Filesharing URL Scheme IETF draft.

SMB URL Examples
URLDescription
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 '/'.

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 ParameterSecond ParameterResult
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:
File

Field Summary
static int ATTR_ARCHIVE
           
static int ATTR_DIRECTORY
           
static int ATTR_HIDDEN
           
static int ATTR_READONLY
           
static int ATTR_SYSTEM
           
static int ATTR_VOLUME
           
static int FILE_NO_SHARE
          When specified as the shareAccess constructor parameter, other SMB clients (including other threads macking calls into jCIFS) will not be permitted to access the target file and will receive "The file is being accessed by another process" message.
static int FILE_SHARE_DELETE
          When specified as the shareAccess constructor parameter, other SMB clients will be permitted to delete the target file while this file is open.
static int FILE_SHARE_READ
          When specified as the shareAccess constructor parameter, other SMB clients will be permitted to read from the target file while this file is open.
static int FILE_SHARE_WRITE
          When specified as the shareAccess constructor parameter, other SMB clients will be permitted to write to the target file while this file is open.
static int TYPE_COMM
          Returned by getType() if the resource this SmbFile represents is a communications device.
static int TYPE_FILESYSTEM
          Returned by getType() if the resource this SmbFile represents is a regular file or directory.
static int TYPE_NAMED_PIPE
          Returned by getType() if the resource this SmbFile represents is a named pipe.
static int TYPE_PRINTER
          Returned by getType() if the resource this SmbFile represents is a printer.
static int TYPE_SERVER
          Returned by getType() if the resource this SmbFile represents is a server.
static int TYPE_SHARE
          Returned by getType() if the resource this SmbFile represents is a share.
static int TYPE_WORKGROUP
          Returned by getType() if the resource this SmbFile represents is a workgroup.
 
Fields inherited from class java.net.URLConnection
allowUserInteraction, connected, doInput, doOutput, ifModifiedSince, url, useCaches
 
Constructor Summary
SmbFile(SmbFile context, java.lang.String name)
          Constructs an SmbFile representing a resource on an SMB network such as a file or directory.
SmbFile(java.lang.String url)
          Constructs an SmbFile representing a resource on an SMB network such as a file or directory.
SmbFile(java.lang.String url, NtlmPasswordAuthentication auth)
          Constructs an SmbFile representing a resource on an SMB network such as a file or directory.
SmbFile(java.lang.String url, NtlmPasswordAuthentication auth, int shareAccess)
          Constructs an SmbFile representing a file on an SMB network.
SmbFile(java.lang.String context, java.lang.String name)
          Constructs an SmbFile representing a resource on an SMB network such as a file or directory.
SmbFile(java.lang.String context, java.lang.String name, NtlmPasswordAuthentication auth)
          Constructs an SmbFile representing a resource on an SMB network such as a file or directory.
SmbFile(java.lang.String context, java.lang.String name, NtlmPasswordAuthentication auth, int shareAccess)
          Constructs an SmbFile representing a resource on an SMB network such as a file or directory.
SmbFile(java.net.URL url)
          Constructs an SmbFile representing a resource on an SMB network such as a file or directory from a URL object.
SmbFile(java.net.URL url, NtlmPasswordAuthentication auth)
          Constructs an SmbFile representing a resource on an SMB network such as a file or directory from a URL object and an NtlmPasswordAuthentication object which may be constructed explicitly or retreived with HttpServletRequest.getUserPrincipal() if NTLM HTTP authentication has been successfully negotiated.
 
Method Summary
 boolean canRead()
          Tests to see if the file this SmbFile represents can be read.
 boolean canWrite()
          Tests to see if the file this SmbFile represents exists and is not marked read-only.
 void connect()
           
 void copyTo(SmbFile dest)
          This method will copy the file or directory and it's subcontents represented by this SmbFile to the location specified by the dest parameter.
 void createNewFile()
           
 long createTime()
          Retrieve the time this SmbFile was created.
 void delete()
          This method will delete the file or directory specified by this SmbFile.
 boolean equals(java.lang.Object obj)
          Tests to see if two SmbFile objects are equal.
 boolean exists()
          Tests to see if the SMB resource exists.
 int getAttributes()
           
 java.lang.String getCanonicalPath()
          Returns the full URL of this SMB resource with '.' and '..' components factored out.
 int getContentLength()
           
 long getDate()
           
 java.lang.String getDfsPath()
          Retrieves the DFS path or null if the path specified does not fall within a DFS volume.
 long getDiskFreeSpace()
          This method returns the free disk space in bytes of the drive this share represents or the drive on which the directory or file resides.
 java.io.InputStream getInputStream()
           
 long getLastModified()
           
 java.lang.String getName()
          Returns the last component of the target URL.
 java.lang.String getParent()
          Everything but the last component of the URL representing this SMB resource is effectivly it's parent.
 java.lang.String getPath()
          Returns the full uncanonicalized URL of this SMB resource.
 java.lang.String getServer()
          Retrieve the hostname of the server for this SMB resource.
 java.lang.String getShare()
          Retrieves the share associated with this SMB resource.
 int getType()
          Returns type of of object this SmbFile represents.
 java.lang.String getUncPath()
          Retuns the Windows UNC style path with backslashs intead of forward slashes.
 int hashCode()
          Computes a hashCode for this file based on the URL string and IP address if the server.
 boolean isDirectory()
          Tests to see if the file this SmbFile represents is a directory.
 boolean isFile()
          Tests to see if the file this SmbFile represents is not a directory.
 boolean isHidden()
          Tests to see if the file this SmbFile represents is marked as hidden.
 long lastModified()
          Retrieve the last time the file represented by this SmbFile was modified.
 long length()
          Returns the length of this SmbFile in bytes.
 java.lang.String[] list()
          List the contents of this SMB resource.
 java.lang.String[] list(SmbFilenameFilter filter)
           
 SmbFile[] listFiles()
          List the contents of this SMB resource as an array of SmbFile objects.
 SmbFile[] listFiles(SmbFileFilter filter)
           
 SmbFile[] listFiles(SmbFilenameFilter filter)
           
 SmbFile[] listFiles(java.lang.String wildcard)
          The CIFS protocol provides for DOS "wildcards" to be used as a performance enhancement.
 void mkdir()
          Creates a directory with the path specified by this SmbFile.
 void mkdirs()
          Creates a directory with the path specified by this SmbFile and any parent directories if necessary.
 void renameTo(SmbFile dest)
          Changes the name of the file this SmbFile represents to the name designated by the SmbFile argument(Remember: SmbFiles are immutible and therefore the path associated with this SmbFile object will not change).
 void setAttributes(int attrs)
           
 void setCreateTime(long time)
           
 void setLastModified(long time)
           
 void setReadOnly()
           
 void setReadWrite()
           
 java.lang.String toString()
          Returns the string representation of this SmbFile object.
 java.net.URL toURL()
          Returns a URL for this SmbFile.
 
Methods inherited from class java.net.URLConnection
getAllowUserInteraction, getContent, getContent, getContentEncoding, getContentType, getDefaultAllowUserInteraction, getDefaultRequestProperty, getDefaultUseCaches, getDoInput, getDoOutput, getExpiration, getFileNameMap, getHeaderField, getHeaderField, getHeaderFieldDate, getHeaderFieldInt, getHeaderFieldKey, getIfModifiedSince, getOutputStream, getPermission, getRequestProperty, getURL, getUseCaches, guessContentTypeFromName, guessContentTypeFromStream, setAllowUserInteraction, setContentHandlerFactory, setDefaultAllowUserInteraction, setDefaultRequestProperty, setDefaultUseCaches, setDoInput, setDoOutput, setFileNameMap, setIfModifiedSince, setRequestProperty, setUseCaches
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

FILE_NO_SHARE

public static final int FILE_NO_SHARE
When specified as the shareAccess constructor parameter, other SMB clients (including other threads macking calls into jCIFS) will not be permitted to access the target file and will receive "The file is being accessed by another process" message.

FILE_SHARE_READ

public static final int FILE_SHARE_READ
When specified as the shareAccess constructor parameter, other SMB clients will be permitted to read from the target file while this file is open. This constant may be logically OR'd with other share access flags.

FILE_SHARE_WRITE

public static final int FILE_SHARE_WRITE
When specified as the shareAccess constructor parameter, other SMB clients will be permitted to write to the target file while this file is open. This constant may be logically OR'd with other share access flags.

FILE_SHARE_DELETE

public static final int FILE_SHARE_DELETE
When specified as the shareAccess constructor parameter, other SMB clients will be permitted to delete the target file while this file is open. This constant may be logically OR'd with other share access flags.

ATTR_READONLY

public static final int ATTR_READONLY

ATTR_HIDDEN

public static final int ATTR_HIDDEN

ATTR_SYSTEM

public static final int ATTR_SYSTEM

ATTR_VOLUME

public static final int ATTR_VOLUME

ATTR_DIRECTORY

public static final int ATTR_DIRECTORY

ATTR_ARCHIVE

public static final int ATTR_ARCHIVE

TYPE_FILESYSTEM

public static final int TYPE_FILESYSTEM
Returned by getType() if the resource this SmbFile represents is a regular file or directory.

TYPE_WORKGROUP

public static final int TYPE_WORKGROUP
Returned by getType() if the resource this SmbFile represents is a workgroup.

TYPE_SERVER

public static final int TYPE_SERVER
Returned by getType() if the resource this SmbFile represents is a server.

TYPE_SHARE

public static final int TYPE_SHARE
Returned by getType() if the resource this SmbFile represents is a share.

TYPE_NAMED_PIPE

public static final int TYPE_NAMED_PIPE
Returned by getType() if the resource this SmbFile represents is a named pipe.

TYPE_PRINTER

public static final int TYPE_PRINTER
Returned by getType() if the resource this SmbFile represents is a printer.

TYPE_COMM

public static final int TYPE_COMM
Returned by getType() if the resource this SmbFile represents is a communications device.
Constructor Detail

SmbFile

public SmbFile(java.lang.String url)
        throws java.net.MalformedURLException
Constructs an SmbFile representing a resource on an SMB network such as a file or directory. See the description and examples of smb URLs above.
Parameters:
url - A URL string
Throws:
java.net.MalformedURLException - If the parent and child parameters do not follow the prescribed syntax

SmbFile

public SmbFile(SmbFile context,
               java.lang.String name)
        throws java.net.MalformedURLException,
               java.net.UnknownHostException
Constructs an SmbFile representing a resource on an SMB network such as a file or directory. The second parameter is a relative path from the parent SmbFile. See the description above for examples of using the second name parameter.
Parameters:
parent - A base SmbFile
child - A path string relative to the parent paremeter
Throws:
java.net.MalformedURLException - If the parent and child parameters do not follow the prescribed syntax
java.net.UnknownHostException - If the server or workgroup of the context file cannot be determined

SmbFile

public SmbFile(java.lang.String context,
               java.lang.String name)
        throws java.net.MalformedURLException
Constructs an SmbFile representing a resource on an SMB network such as a file or directory. The second parameter is a relative path from the parent. See the description above for examples of using the second chile parameter.
Parameters:
context - A URL string
name - A path string relative to the context paremeter
Throws:
java.net.MalformedURLException - If the context and name parameters do not follow the prescribed syntax

SmbFile

public SmbFile(java.lang.String url,
               NtlmPasswordAuthentication auth)
        throws java.net.MalformedURLException
Constructs an SmbFile representing a resource on an SMB network such as a file or directory. The second parameter may be constructed explicitly or retreived with HttpServletRequest.getUserPrincipal() if NTLM HTTP authentication has been successfully negotiated.
Parameters:
url - A URL string
auth - The credentials the client should use for authentication
Throws:
java.net.MalformedURLException - If the url parameter does not follow the prescribed syntax

SmbFile

public SmbFile(java.lang.String url,
               NtlmPasswordAuthentication auth,
               int shareAccess)
        throws java.net.MalformedURLException
Constructs an SmbFile representing a file on an SMB network. The second parameter may be constructed explicitly or retreived with HttpServletRequest.getUserPrincipal() if NTLM HTTP authentication has been successfully negotiated. The shareAccess parameter controls what permissions other clients have when trying to access the same file while this instance is still open. This value is either FILE_NO_SHARE or any combination of FILE_SHARE_READ, FILE_SHARE_WRITE, and FILE_SHARE_DELETE logically OR'd together.
Parameters:
url - A URL string
auth - The credentials the client should use for authentication
shareAccess - Specifies what access other clients have while this file is open.
Throws:
java.net.MalformedURLException - If the url parameter does not follow the prescribed syntax

SmbFile

public SmbFile(java.lang.String context,
               java.lang.String name,
               NtlmPasswordAuthentication auth)
        throws java.net.MalformedURLException
Constructs an SmbFile representing a resource on an SMB network such as a file or directory. The second parameter is a relative path from the context. See the description above for examples of using the second name parameter. The third parameter may be constructed explicitly or retreived with HttpServletRequest.getUserPrincipal() if NTLM HTTP authentication has been successfully negotiated.
Parameters:
context - A URL string
name - A path string relative to the context paremeter
auth - The credentials the client should use for authentication
Throws:
java.net.MalformedURLException - If the context and name parameters do not follow the prescribed syntax

SmbFile

public SmbFile(java.lang.String context,
               java.lang.String name,
               NtlmPasswordAuthentication auth,
               int shareAccess)
        throws java.net.MalformedURLException
Constructs an SmbFile representing a resource on an SMB network such as a file or directory. The second parameter is a relative path from the context. See the description above for examples of using the second name parameter. The third parameter may be constructed explicitly or retreived with HttpServletRequest.getUserPrincipal() if NTLM HTTP authentication has been successfully negotiated. The shareAccess parameter controls what permissions other clients have when trying to access the same file while this instance is still open. This value is either FILE_NO_SHARE or any combination of FILE_SHARE_READ, FILE_SHARE_WRITE, and FILE_SHARE_DELETE logically OR'd together.
Parameters:
context - A URL string
name - A path string relative to the context paremeter
auth - The credentials the client should use for authentication
shareAccess - Specifies what access other clients have while this file is open.
Throws:
java.net.MalformedURLException - If the context and name parameters do not follow the prescribed syntax

SmbFile

public SmbFile(java.net.URL url)
Constructs an SmbFile representing a resource on an SMB network such as a file or directory from a URL object.
Parameters:
url - The URL of the target resource

SmbFile

public SmbFile(java.net.URL url,
               NtlmPasswordAuthentication auth)
Constructs an SmbFile representing a resource on an SMB network such as a file or directory from a URL object and an NtlmPasswordAuthentication object which may be constructed explicitly or retreived with HttpServletRequest.getUserPrincipal() if NTLM HTTP authentication has been successfully negotiated.
Parameters:
url - The URL of the target resource
auth - The credentials the client should use for authentication
Method Detail

connect

public void connect()
             throws java.io.IOException
Overrides:
connect in class java.net.URLConnection

getName

public java.lang.String getName()
Returns the last component of the target URL. This will effectively be the name of the file or directory represented by this SmbFile or in the case of URLs that only specify a server or workgroup, the server or workgroup will be returned. The name of the root URL smb:// is also smb://. If this SmbFile refers to a workgroup, server, share, or directory, the name will include a trailing slash '/' so that composing new SmbFiles will maintain the trailing slash requirement introduced in jcifs-0.7.0b4.
Returns:
The last component of the URL associated with this SMB resource or smb:// if the resource is smb:// itself.

getParent

public java.lang.String getParent()
Everything but the last component of the URL representing this SMB resource is effectivly it's parent. The root URL smb:// does not have a parent. In this case smb:// is returned.
Returns:
The parent directory of this SMB resource or smb:// if the resource refers to the root of the URL hierarchy which incedentally is also smb://.

getPath

public java.lang.String getPath()
Returns the full uncanonicalized URL of this SMB resource. An SmbFile constructed with the result of this method will result in an SmbFile that is equal to the original.
Returns:
The uncanonicalized full URL of this SMB resource.

getUncPath

public java.lang.String getUncPath()
Retuns the Windows UNC style path with backslashs intead of forward slashes.
Returns:
The UNC path.

getCanonicalPath

public java.lang.String getCanonicalPath()
Returns the full URL of this SMB resource with '.' and '..' components factored out. An SmbFile constructed with the result of this method will result in an SmbFile that is equal to the original.
Returns:
The canonicalized URL of this SMB resource.

getShare

public java.lang.String getShare()
Retrieves the share associated with this SMB resource. In the case of smb://, smb://workgroup, and smb://server URLs which do not specify a share, null will be returned.
Returns:
The share component or null if there is no share

getServer

public java.lang.String getServer()
Retrieve the hostname of the server for this SMB resource. If this SmbFile references a workgroup, the name of the workgroup is returned. If this SmbFile refers to the root of this SMB network hierarchy, null is returned.
Returns:
The server or workgroup name or null if this SmbFile refers to the root smb:// resource.

getType

public int getType()
            throws SmbException
Returns type of of object this SmbFile represents.
Returns:
TYPE_FILESYSTEM, TYPE_WORKGROUP, TYPE_SERVER, TYPE_SHARE, TYPE_PRINTER, TYPE_NAMED_PIPE, or TYPE_COMM.

exists

public boolean exists()
               throws SmbException
Tests to see if the SMB resource exists. If the resource refers only to a server, this method determines if the server exists on the network and is advertising SMB services. If this resource refers to a workgroup, this method determines if the workgroup name is valid on the local SMB network. If this SmbFile refers to the root smb:// resource true is always returned. If this SmbFile is a traditional file or directory, it will be queried for on the specified server as expected.
Returns:
true if the resource exists or is alive or false otherwise

canRead

public boolean canRead()
                throws SmbException
Tests to see if the file this SmbFile represents can be read. Because any file, directory, or other resource can be read if it exists, this method simply calls the exists method.
Returns:
true if the file is read-only

canWrite

public boolean canWrite()
                 throws SmbException
Tests to see if the file this SmbFile represents exists and is not marked read-only. By default, resources are considered to be read-only and therefore for smb://, smb://workgroup, and smb://server resources will be read-only.
Returns:
true if the resource exists is not marked read-only

isDirectory

public boolean isDirectory()
                    throws SmbException
Tests to see if the file this SmbFile represents is a directory.
Returns:
true if this SmbFile is a directory

isFile

public boolean isFile()
               throws SmbException
Tests to see if the file this SmbFile represents is not a directory.
Returns:
true if this SmbFile is not a directory

isHidden

public boolean isHidden()
                 throws SmbException
Tests to see if the file this SmbFile represents is marked as hidden.
Returns:
true if the SmbFile is marked as being hidden

getDfsPath

public java.lang.String getDfsPath()
                            throws SmbException
Retrieves the DFS path or null if the path specified does not fall within a DFS volume.

createTime

public long createTime()
                throws SmbException
Retrieve the time this SmbFile was created. The value returned is suitable for constructing a Date object and is adjusted for the servers timezone differential. Times should be the same as those reported using the properties dialog of the Windows Explorer program. For Win95/98/Me this is actually the last write time. It is currently not possible to retrieve the create time from files on these systems.
Returns:
The number of milliseconds since the 00:00:00 GMT, January 1, 1970 as a long value

lastModified

public long lastModified()
                  throws SmbException
Retrieve the last time the file represented by this SmbFile was modified. The value returned is suitable for constructing a Date object and is adjusted for the servers timezone differential. Times should be the same as those reported using the properties dialog of the Windows Explorer program.
Returns:
The number of milliseconds since the 00:00:00 GMT, January 1, 1970 as a long value

list

public java.lang.String[] list()
                        throws SmbException
List the contents of this SMB resource. The list 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.
Returns:
A String[] array of files and directories, workgroups, servers, or shares depending on the context of the resource URL

list

public java.lang.String[] list(SmbFilenameFilter filter)
                        throws SmbException

listFiles

public SmbFile[] listFiles()
                    throws SmbException
List the contents of this SMB resource as an array of SmbFile objects. This method is much more efficient than the regular list method when querying attributes of each file in the result set.

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.
Returns:
An array of SmbFile objects representing file and directories, workgroups, servers, or shares depending on the context of the resource URL

listFiles

public SmbFile[] listFiles(java.lang.String wildcard)
                    throws SmbException
The CIFS protocol provides for DOS "wildcards" to be used as a performance enhancement. The client does not have to filter the names ane the server does not have to return all directory entries.

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
 
Parameters:
wildcard - a wildcard expression
Returns:
An array of SmbFile objects representing file and directories, workgroups, servers, or shares depending on the context of the resource URL
Throws:
SmbException -  

listFiles

public SmbFile[] listFiles(SmbFilenameFilter filter)
                    throws SmbException

listFiles

public SmbFile[] listFiles(SmbFileFilter filter)
                    throws SmbException

renameTo

public void renameTo(SmbFile dest)
              throws SmbException
Changes the name of the file this SmbFile represents to the name designated by the SmbFile argument(Remember: SmbFiles are immutible and therefore the path associated with this SmbFile object will not change).
Parameters:
dest - An SmbFile that represents the new pathname
Returns:
true if the file or directory was successfully renamed
Throws:
NullPointerException - If the dest argument is null

copyTo

public void copyTo(SmbFile dest)
            throws SmbException
This method will copy the file or directory and it's subcontents represented by this SmbFile to the location specified by the dest parameter. This file and the destination file do not need to be on the same host. This operation does not copy extended file attibutes such as ACLs but regular attributes and create and last write times will be preserved.

delete

public void delete()
            throws SmbException
This method will delete the file or directory specified by this SmbFile. If the target is a directory, the contents of the directory will be deleted as well. If the resource or sub-resource is marked read-only or is locked the operation will fail. There is currently no functionality to set the attributes of a file, break locks, or disconnect users.
Throws:
SmbException -  

length

public long length()
            throws SmbException
Returns the length of this SmbFile in bytes. If this object is a TYPE_SHARE the total capacity of the disk shared in bytes is returned. If this object is a directory or a type other than TYPE_SHARE, 0L is returned.
Returns:
The length of the file in bytes or 0 if this SmbFile is not a file.

getDiskFreeSpace

public long getDiskFreeSpace()
                      throws SmbException
This method returns the free disk space in bytes of the drive this share represents or the drive on which the directory or file resides. Objects other than TYPE_SHARE or TYPE_FILESYSTEM will result in 0L being returned.

mkdir

public void mkdir()
           throws SmbException
Creates a directory with the path specified by this SmbFile. For this method to be successfull, the target must not already exist. This method will fail when used with smb://, smb://workgroup, smb://server, or smb://server/share URLs because workgroups, servers, and shares cannot be dynamically created.
Throws:
SmbException -  

mkdirs

public void mkdirs()
            throws SmbException
Creates a directory with the path specified by this SmbFile and any parent directories if necessary. For this method to be successfull, the target must not already exist. This method will fail when used with smb://, smb://workgroup, smb://server, or smb://server/share URLs because workgroups, servers, and shares cannot be dynamically created.
Throws:
SmbException -  

createNewFile

public void createNewFile()
                   throws SmbException

setCreateTime

public void setCreateTime(long time)
                   throws SmbException

setLastModified

public void setLastModified(long time)
                     throws SmbException

getAttributes

public int getAttributes()
                  throws SmbException

setAttributes

public void setAttributes(int attrs)
                   throws SmbException

setReadOnly

public void setReadOnly()
                 throws SmbException

setReadWrite

public void setReadWrite()
                  throws SmbException

toURL

public java.net.URL toURL()
                   throws java.net.MalformedURLException
Returns a URL for this SmbFile. The URL may be used as any other URL might to access an SMB resource. Currently only retrieving data and information is supported.
Returns:
A new URL for this SmbFile

hashCode

public int hashCode()
Computes a hashCode for this file based on the URL string and IP address if the server. The hashing function uses the hashcode of the server address, the canonical representation of the URL, and does not compare authentication information. In essance, two SmbFile objects that refer to the same file should generate the same hashcode provided it is possible to make such a determination.
Overrides:
hashCode in class java.lang.Object
Returns:
A hashcode for this abstract file

equals

public boolean equals(java.lang.Object obj)
Tests to see if two SmbFile objects are equal. Two SmbFile objects are equal when they reference the same SMB resource. More specifically, two SmbFile objects are equals if their server IP addresses are equal and the canonicalized representation of their URLs, minus authentication parameters, are case insensitivly and lexographically equal. 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
 
Overrides:
equals in class java.lang.Object
Parameters:
obj - Another SmbFile object to compare for equality
Returns:
true if the two objects refer to the same SMB resource and false otherwise

toString

public java.lang.String toString()
Returns the string representation of this SmbFile object. This will be the same as the URL used to construct this SmbFile. This method will return the same value as getPath.
Overrides:
toString in class java.net.URLConnection
Returns:
The original URL representation of this SMB resource

getContentLength

public int getContentLength()
Overrides:
getContentLength in class java.net.URLConnection

getDate

public long getDate()
Overrides:
getDate in class java.net.URLConnection

getLastModified

public long getLastModified()
Overrides:
getLastModified in class java.net.URLConnection

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException
Overrides:
getInputStream in class java.net.URLConnection