jcifs.smb

Class SmbFile

java.lang.Object

java.net.URLConnection

jcifs.smb.SmbFile

All Implemented Interfaces:

AutoCloseable, SmbConstants, SmbResource

Direct Known Subclasses:

SmbNamedPipe

public class SmbFile
extends URLConnection
implements SmbResource, SmbConstants

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 [1] to specify the target file or directory. SmbFile URLs have the following syntax:

     smb://[[[domain;]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 relatively 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://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://server/share/path/to/dir <-- ILLEGAL	URLs that represent 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 constructor 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/

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

Fields inherited from interface jcifs.SmbConstants

ATTR_ARCHIVE, ATTR_COMPRESSED, ATTR_DIRECTORY, ATTR_HIDDEN, ATTR_NORMAL, ATTR_READONLY, ATTR_SYSTEM, ATTR_TEMPORARY, ATTR_VOLUME, CAP_DFS, CAP_EXTENDED_SECURITY, CAP_LARGE_FILES, CAP_LARGE_READX, CAP_LARGE_WRITEX, CAP_LEVEL_II_OPLOCKS, CAP_LOCK_AND_READ, CAP_MPX_MODE, CAP_NONE, CAP_NT_FIND, CAP_NT_SMBS, CAP_RAW_MODE, CAP_RPC_REMOTE_APIS, CAP_STATUS32, CAP_UNICODE, CMD_OFFSET, DEFAULT_CONN_TIMEOUT, DEFAULT_MAX_MPX_COUNT, DEFAULT_NOTIFY_BUF_SIZE, DEFAULT_OEM_ENCODING, DEFAULT_PORT, DEFAULT_RCV_BUF_SIZE, DEFAULT_RESPONSE_TIMEOUT, DEFAULT_SHARING, DEFAULT_SND_BUF_SIZE, DEFAULT_SO_TIMEOUT, DEFAULT_SSN_LIMIT, DELETE, ERROR_CODE_OFFSET, FILE_APPEND_DATA, FILE_DELETE, FILE_EXECUTE, FILE_NO_SHARE, FILE_READ_ATTRIBUTES, FILE_READ_DATA, FILE_READ_EA, FILE_SHARE_DELETE, FILE_SHARE_READ, FILE_SHARE_WRITE, FILE_WRITE_ATTRIBUTES, FILE_WRITE_DATA, FILE_WRITE_EA, FLAGS_COPY_SOURCE_MODE_ASCII, FLAGS_COPY_TARGET_MODE_ASCII, FLAGS_LOCK_AND_READ_WRITE_AND_UNLOCK, FLAGS_NONE, FLAGS_NOTIFY_OF_MODIFY_ACTION, FLAGS_OFFSET, FLAGS_OPLOCK_REQUESTED_OR_GRANTED, FLAGS_PATH_NAMES_CANONICALIZED, FLAGS_PATH_NAMES_CASELESS, FLAGS_RECEIVE_BUFFER_POSTED, FLAGS_RESPONSE, FLAGS_TARGET_MUST_BE_DIRECTORY, FLAGS_TARGET_MUST_BE_FILE, FLAGS_TREE_COPY, FLAGS_VERIFY_ALL_WRITES, FLAGS2_EXTENDED_ATTRIBUTES, FLAGS2_EXTENDED_SECURITY_NEGOTIATION, FLAGS2_LONG_FILENAMES, FLAGS2_NONE, FLAGS2_PERMIT_READ_IF_EXECUTE_PERM, FLAGS2_RESOLVE_PATHS_IN_DFS, FLAGS2_SECURITY_REQUIRE_SIGNATURES, FLAGS2_SECURITY_SIGNATURES, FLAGS2_STATUS32, FLAGS2_UNICODE, FOREVER, GENERIC_ALL, GENERIC_EXECUTE, GENERIC_READ, GENERIC_WRITE, MILLISECONDS_BETWEEN_1970_AND_1601, O_APPEND, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_TRUNC, O_WRONLY, OPEN_FUNCTION_FAIL_IF_EXISTS, OPEN_FUNCTION_OVERWRITE_IF_EXISTS, READ_CONTROL, SECURITY_SHARE, SECURITY_USER, SIGNATURE_OFFSET, SMB1_HEADER_LENGTH, SYNCHRONIZE, TID_OFFSET, TYPE_COMM, TYPE_FILESYSTEM, TYPE_NAMED_PIPE, TYPE_PRINTER, TYPE_SERVER, TYPE_SHARE, TYPE_WORKGROUP, WRITE_DAC, WRITE_OWNER

Constructor Summary

Constructors

Constructor and Description
SmbFile(SmbResource context, String name) Constructs an SmbFile representing a resource on an SMB network such as a file or directory.
SmbFile(String url) Deprecated.
SmbFile(String url, CIFSContext tc) Construct from string URL
SmbFile(URL url) Deprecated.
SmbFile(URL url, CIFSContext tc) Construct from URL

Method Summary

Modifier and Type	Method and Description
boolean	canRead() Tests to see if the file this SmbResource represents can be read.
boolean	canWrite() Tests to see if the file this SmbResource represents exists and is not marked read-only.
CloseableIterator<SmbResource>	children() Fetch all children
CloseableIterator<SmbResource>	children(ResourceFilter filter)
CloseableIterator<SmbResource>	children(ResourceNameFilter filter)
CloseableIterator<SmbResource>	children(String wildcard) Fetch children matching pattern, server-side filtering
void	close() Close/release the file This releases all resources that this file holds.
void	connect()
void	copyTo(SmbResource d) This method will copy the file or directory represented by this SmbResource and it's sub-contents to the location specified by the dest parameter.
void	createNewFile() Create a new file but fail if it already exists.
long	createTime() Retrieve the time this SmbResource was created.
void	delete() This method will delete the file or directory specified by this SmbResource.
boolean	equals(Object obj) Tests to see if two SmbFile objects are equal.
boolean	exists() Tests to see if the SMB resource exists.
long	fileIndex() Get the file index
int	getAttributes() Return the attributes of this file.
String	getCanonicalPath() Returns the full URL of this SMB resource with '.' and '..' components factored out.
String	getCanonicalUncPath() Returns the Windows UNC style path with backslashes instead of forward slashes.
int	getContentLength() Deprecated.
long	getContentLengthLong()
CIFSContext	getContext() The context this file was opened with
long	getDate() This URLConnection method just returns the result of lastModified.
String	getDfsPath() If the path of this SmbFile falls within a DFS volume, this method will return the referral path to which it maps.
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.
InputStream	getInputStream() This URLConnection method just returns a new SmbFileInputStream created with this file.
long	getLastModified() This URLConnection method just returns the result of lastModified.
SmbResourceLocator	getLocator() Gets the file locator for this file The file locator provides details about
String	getName() Returns the last component of the target URL.
OutputStream	getOutputStream()
SID	getOwnerGroup() Return the resolved owner group SID for this file or directory
SID	getOwnerGroup(boolean resolve) Return the owner group SID for this file or directory
SID	getOwnerUser() Return the resolved owner user SID for this file or directory
SID	getOwnerUser(boolean resolve) Return the owner user SID for this file or directory
String	getParent() Everything but the last component of the URL representing this SMB resource is effectively it's parent.
String	getPath() Returns the full uncanonicalized URL of this SMB resource.
ACE[]	getSecurity() Return an array of Access Control Entry (ACE) objects representing the security descriptor associated with this file or directory.
ACE[]	getSecurity(boolean resolveSids) Return an array of Access Control Entry (ACE) objects representing the security descriptor associated with this file or directory.
String	getServer() Retrieve the hostname of the server for this SMB resource.
String	getServerWithDfs() Retrieve the hostname of the server for this SMB resource.
String	getShare() Retrieves the share associated with this SMB resource.
ACE[]	getShareSecurity(boolean resolveSids) Return an array of Access Control Entry (ACE) objects representing the share permissions on the share exporting this file or directory.
CIFSContext	getTransportContext() Deprecated.
SmbTreeHandle	getTreeHandle()
int	getType() Returns type of of object this SmbResource represents.
String	getUncPath()
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 SmbResource represents is a directory.
boolean	isFile() Tests to see if the file this SmbResource represents is not a directory.
boolean	isHidden() Tests to see if the file this SmbResource represents is marked as hidden.
long	lastAccess() Retrieve the last acces time of the file represented by this SmbResource
long	lastModified() Retrieve the last time the file represented by this SmbResource was modified.
long	length() Returns the length of this SmbResource in bytes.
String[]	list() List the contents of this SMB resource.
String[]	list(SmbFilenameFilter filter) List the contents of this SMB resource.
SmbFile[]	listFiles() List the contents of this SMB resource as an array of SmbResource objects.
SmbFile[]	listFiles(SmbFileFilter filter) List the contents of this SMB resource.
SmbFile[]	listFiles(SmbFilenameFilter filter) List the contents of this SMB resource.
SmbFile[]	listFiles(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 SmbResource.
void	mkdirs() Creates a directory with the path specified by this SmbResource and any parent directories that do not exist.
SmbFileInputStream	openInputStream() Opens an input stream reading the file (read only, sharable)
SmbFileInputStream	openInputStream(int sharing) Opens an input stream reading the file (read only)
SmbFileInputStream	openInputStream(int flags, int access, int sharing) Opens an input stream reading the file (read only)
SmbFileOutputStream	openOutputStream() Opens an output stream writing to the file (truncating, write only, sharable)
SmbFileOutputStream	openOutputStream(boolean append) Opens an output stream writing to the file (write only, read sharable)
SmbFileOutputStream	openOutputStream(boolean append, int sharing) Opens an output stream writing to the file (write only, exclusive write access)
SmbFileOutputStream	openOutputStream(boolean append, int openFlags, int access, int sharing) Opens an output stream writing to the file (write only, exclusive write access)
SmbRandomAccessFile	openRandomAccess(String mode) Opens the file for random access
SmbRandomAccessFile	openRandomAccess(String mode, int sharing) Opens the file for random access
void	renameTo(SmbResource d) Changes the name of the file this SmbResource represents to the name designated by the SmbResource argument.
void	renameTo(SmbResource d, boolean replace) Changes the name of the file this SmbResource represents to the name designated by the SmbResource argument.
SmbResource	resolve(String name) Fetch a child resource
void	setAttributes(int attrs) Set the attributes of this file.
void	setCreateTime(long time) Set the create time of the file.
void	setFileTimes(long createTime, long lastLastModified, long lastLastAccess) Set the create, last modified and last access time of the file.
void	setLastAccess(long time) Set the last access time of the file.
void	setLastModified(long time) Set the last modified time of the file.
void	setReadOnly() Make this file read-only.
void	setReadWrite() Turn off the read-only attribute of this file.
String	toString() Returns the string representation of this SmbFile object.
URL	toURL() Deprecated. Use getURL() instead
SmbWatchHandle	watch(int filter, boolean recursive) Creates a directory watch The server will notify the client when there are changes to the directories contents

Methods inherited from class java.net.URLConnection

addRequestProperty, getAllowUserInteraction, getConnectTimeout, getContent, getContent, getContentEncoding, getContentType, getDefaultAllowUserInteraction, getDefaultRequestProperty, getDefaultUseCaches, getDoInput, getDoOutput, getExpiration, getFileNameMap, getHeaderField, getHeaderField, getHeaderFieldDate, getHeaderFieldInt, getHeaderFieldKey, getHeaderFieldLong, getHeaderFields, getIfModifiedSince, getPermission, getReadTimeout, getRequestProperties, getRequestProperty, getURL, getUseCaches, guessContentTypeFromName, guessContentTypeFromStream, setAllowUserInteraction, setConnectTimeout, setContentHandlerFactory, setDefaultAllowUserInteraction, setDefaultRequestProperty, setDefaultUseCaches, setDoInput, setDoOutput, setFileNameMap, setIfModifiedSince, setReadTimeout, setRequestProperty, setUseCaches

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

SmbFile

@Deprecated
public SmbFile(String url)
                    throws MalformedURLException

Deprecated.

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:

MalformedURLException - If the parent and child parameters do not follow the prescribed syntax

SmbFile

@Deprecated
public SmbFile(URL url)
                    throws MalformedURLException

Deprecated.

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

Throws:

MalformedURLException

SmbFile

public SmbFile(SmbResource context,
               String name)
        throws MalformedURLException,
               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:

context - A base SmbFile

name - A path string relative to the parent parameter

Throws:

MalformedURLException - If the parent and child parameters do not follow the prescribed syntax

UnknownHostException - If the server or workgroup of the context file cannot be determined

SmbFile

public SmbFile(String url,
               CIFSContext tc)
        throws MalformedURLException

Construct from string URL

Parameters:

url -

tc - context to use

Throws:

MalformedURLException

SmbFile

public SmbFile(URL url,
               CIFSContext tc)
        throws MalformedURLException

Construct from URL

Parameters:

url -

tc - context to use

Throws:

MalformedURLException

Method Detail

connect

public void connect()
             throws IOException

Specified by:

connect in class URLConnection

Throws:

IOException

See Also:

URLConnection.connect()

getTreeHandle

public SmbTreeHandle getTreeHandle()
                            throws CIFSException

Returns:

a tree handle

Throws:

CIFSException

close

public void close()

Close/release the file This releases all resources that this file holds. If not using strict mode this is currently a no-op.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface SmbResource

See Also:

AutoCloseable.close()

getTransportContext

@Deprecated
public CIFSContext getTransportContext()

Deprecated.

Returns:

the transportContext

getContext

public CIFSContext getContext()

Description copied from interface: SmbResource

The context this file was opened with

Specified by:

getContext in interface SmbResource

Returns:

the context associated with this file

getLocator

public SmbResourceLocator getLocator()

Description copied from interface: SmbResource

Gets the file locator for this file The file locator provides details about

Specified by:

getLocator in interface SmbResource

Returns:

the fileLocator

resolve

public SmbResource resolve(String name)
                    throws CIFSException

Description copied from interface: SmbResource

Fetch a child resource

Specified by:

resolve in interface SmbResource

Returns:

the child resource

Throws:

CIFSException

getUncPath

public String getUncPath()

Returns:

this file's unc path below the share

exists

public boolean exists()
               throws SmbException

Description copied from interface: SmbResource

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 SmbResource refers to the root smb:// resource true is always returned. If this SmbResource is a traditional file or directory, it will be queried for on the specified server as expected.

Specified by:

exists in interface SmbResource

Returns:

true if the resource exists or is alive or false otherwise

Throws:

SmbException

getType

public int getType()
            throws SmbException

Description copied from interface: SmbResource

Returns type of of object this SmbResource represents.

Specified by:

getType in interface SmbResource

Returns:

TYPE_FILESYSTEM, TYPE_WORKGROUP, TYPE_SERVER, TYPE_SHARE, TYPE_PRINTER, TYPE_NAMED_PIPE, or TYPE_COMM.

Throws:

SmbException

getName

public String getName()

Description copied from interface: SmbResource

Returns the last component of the target URL. This will effectively be the name of the file or directory represented by this SmbResource 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 SmbResource refers to a workgroup, server, share, or directory, the name will include a trailing slash '/' so that composing new SmbResources will maintain the trailing slash requirement.

Specified by:

getName in interface SmbResource

Returns:

The last component of the URL associated with this SMB resource or smb:// if the resource is smb:// itself.

getParent

public String getParent()

Everything but the last component of the URL representing this SMB resource is effectively 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 incidentally is also smb://.

getPath

public 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.

getCanonicalUncPath

public String getCanonicalUncPath()

Returns the Windows UNC style path with backslashes instead of forward slashes.

Returns:

The UNC path.

getDfsPath

public String getDfsPath()
                  throws SmbException

If the path of this SmbFile falls within a DFS volume, this method will return the referral path to which it maps. Otherwise null is returned.

Returns:

URL to the DFS volume

Throws:

SmbException

getCanonicalPath

public 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 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

getServerWithDfs

public String getServerWithDfs()

Retrieve the hostname of the server for this SMB resource. If the resources has been resolved by DFS this will return the target name.

Returns:

The server name

getServer

public 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.

watch

public SmbWatchHandle watch(int filter,
                            boolean recursive)
                     throws CIFSException

Description copied from interface: SmbResource

Creates a directory watch The server will notify the client when there are changes to the directories contents

Specified by:

watch in interface SmbResource

Parameters:

filter - see constants in FileNotifyInformation

recursive - whether to also watch subdirectories

Returns:

watch context, needs to be closed when finished

Throws:

CIFSException

canRead

public boolean canRead()
                throws SmbException

Description copied from interface: SmbResource

Tests to see if the file this SmbResource represents can be read. Because any file, directory, or other resource can be read if it exists, this method simply calls the exists method.

Specified by:

canRead in interface SmbResource

Returns:

true if the file is read-only

Throws:

SmbException

canWrite

public boolean canWrite()
                 throws SmbException

Description copied from interface: SmbResource

Tests to see if the file this SmbResource 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.

Specified by:

canWrite in interface SmbResource

Returns:

true if the resource exists is not marked read-only

Throws:

SmbException

isDirectory

public boolean isDirectory()
                    throws SmbException

Description copied from interface: SmbResource

Tests to see if the file this SmbResource represents is a directory.

Specified by:

isDirectory in interface SmbResource

Returns:

true if this SmbResource is a directory

Throws:

SmbException

isFile

public boolean isFile()
               throws SmbException

Description copied from interface: SmbResource

Tests to see if the file this SmbResource represents is not a directory.

Specified by:

isFile in interface SmbResource

Returns:

true if this SmbResource is not a directory

Throws:

SmbException

isHidden

public boolean isHidden()
                 throws SmbException

Description copied from interface: SmbResource

Tests to see if the file this SmbResource represents is marked as hidden. This method will also return true for shares with names that end with '$' such as IPC$ or C$.

Specified by:

isHidden in interface SmbResource

Returns:

true if the SmbResource is marked as being hidden

Throws:

SmbException

createTime

public long createTime()
                throws SmbException

Description copied from interface: SmbResource

Retrieve the time this SmbResource was created. The value returned is suitable for constructing a Date object (i.e. seconds since Epoch 1970). 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.

Specified by:

createTime in interface SmbResource

Returns:

The number of milliseconds since the 00:00:00 GMT, January 1, 1970 as a long value

Throws:

SmbException

lastModified

public long lastModified()
                  throws SmbException

Description copied from interface: SmbResource

Retrieve the last time the file represented by this SmbResource was modified. The value returned is suitable for constructing a Date object (i.e. seconds since Epoch 1970). Times should be the same as those reported using the properties dialog of the Windows Explorer program.

Specified by:

lastModified in interface SmbResource

Returns:

The number of milliseconds since the 00:00:00 GMT, January 1, 1970 as a long value

Throws:

SmbException

lastAccess

public long lastAccess()
                throws SmbException

Description copied from interface: SmbResource

Retrieve the last acces time of the file represented by this SmbResource

Specified by:

lastAccess in interface SmbResource

Returns:

The number of milliseconds since the 00:00:00 GMT, January 1, 1970 as a long value

Throws:

SmbException

list

public 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

Throws:

SmbException

list

public String[] list(SmbFilenameFilter filter)
              throws SmbException

List the contents of this SMB resource. The list returned will be identical to the list returned by the parameterless list() method minus filenames filtered by the specified filter.

Parameters:

filter - a filename filter to exclude filenames from the results

Returns:

String[] array of matching files and directories, workgroups, servers, or shares depending on the context of the resource URL

Throws:

SmbException - # @return An array of filenames

listFiles

public SmbFile[] listFiles()
                    throws SmbException

List the contents of this SMB resource as an array of SmbResource 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 SmbResources 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.

If strict resource lifecycle is used, make sure you close the individual files after use.

Returns:

An array of SmbResource objects representing file and directories, workgroups, servers, or shares depending on the context of the resource URL

Throws:

SmbException

listFiles

public SmbFile[] listFiles(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 and 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
 

If strict resource lifecycle is used, make sure you close the individual files after use.

Parameters:

wildcard - a wildcard expression

Returns:

An array of SmbResource 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

List the contents of this SMB resource. The list returned will be identical to the list returned by the parameterless listFiles() method minus files filtered by the specified filename filter. If strict resource lifecycle is used, make sure you close the individual files after use.

Parameters:

filter - a filter to exclude files from the results

Returns:

An array of SmbResource objects

Throws:

SmbException

listFiles

public SmbFile[] listFiles(SmbFileFilter filter)
                    throws SmbException

List the contents of this SMB resource. The list returned will be identical to the list returned by the parameterless listFiles() method minus filenames filtered by the specified filter. If strict resource lifecycle is used, make sure you close the individual files after use.

Parameters:

filter - a file filter to exclude files from the results

Returns:

An array of SmbResource objects

Throws:

SmbException

children

public CloseableIterator<SmbResource> children()
                                        throws CIFSException

Description copied from interface: SmbResource

Fetch all children

Specified by:

children in interface SmbResource

Returns:

an iterator over the child resources

Throws:

CIFSException

children

public CloseableIterator<SmbResource> children(String wildcard)
                                        throws CIFSException

Description copied from interface: SmbResource

Fetch children matching pattern, server-side filtering

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.

Specified by:

children in interface SmbResource

Returns:

an iterator over the child resources

Throws:

CIFSException

children

public CloseableIterator<SmbResource> children(ResourceNameFilter filter)
                                        throws CIFSException

Specified by:

children in interface SmbResource

Parameters:

filter - filter acting on file names

Returns:

an iterator over the child resources

Throws:

CIFSException

See Also:

for a more efficient way to do this when a pattern on the filename is sufficient for filtering

children

public CloseableIterator<SmbResource> children(ResourceFilter filter)
                                        throws CIFSException

Specified by:

children in interface SmbResource

Parameters:

filter - filter acting on SmbResource instances

Returns:

an iterator over the child resources

Throws:

CIFSException

See Also:

for a more efficient way to do this when a pattern on the filename is sufficient for filtering

renameTo

public void renameTo(SmbResource d)
              throws SmbException

Description copied from interface: SmbResource

Changes the name of the file this SmbResource represents to the name designated by the SmbResource argument.
Remember: SmbResources are immutable and therefore the path associated with this SmbResource object will not change). To access the renamed file it is necessary to construct a new SmbResource.

Specified by:

renameTo in interface SmbResource

Parameters:

d - An SmbResource that represents the new pathname

Throws:

SmbException

renameTo

public void renameTo(SmbResource d,
                     boolean replace)
              throws SmbException

Description copied from interface: SmbResource

Changes the name of the file this SmbResource represents to the name designated by the SmbResource argument.
Remember: SmbResources are immutable and therefore the path associated with this SmbResource object will not change). To access the renamed file it is necessary to construct a new SmbResource.

Specified by:

renameTo in interface SmbResource

Parameters:

d - An SmbResource that represents the new pathname

replace - Whether an existing destination file should be replaced (only supported with SMB2)

Throws:

SmbException

copyTo

public void copyTo(SmbResource d)
            throws SmbException

Description copied from interface: SmbResource

This method will copy the file or directory represented by this SmbResource and it's sub-contents 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 attributes such as ACLs but it does copy regular attributes as well as create and last write times. This method is almost twice as efficient as manually copying as it employs an additional write thread to read and write data concurrently.
It is not possible (nor meaningful) to copy entire workgroups or servers.

Specified by:

copyTo in interface SmbResource

Parameters:

d - the destination file or directory

Throws:

SmbException

delete

public void delete()
            throws SmbException

Description copied from interface: SmbResource

This method will delete the file or directory specified by this SmbResource. If the target is a directory, the contents of the directory will be deleted as well. If a file within the directory or it's sub-directories is marked read-only, the read-only status will be removed and the file will be deleted. If the file has been opened before, it will be closed.

Specified by:

delete in interface SmbResource

Throws:

SmbException

length

public long length()
            throws SmbException

Description copied from interface: SmbResource

Returns the length of this SmbResource 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.

Specified by:

length in interface SmbResource

Returns:

The length of the file in bytes or 0 if this SmbResource is not a file.

Throws:

SmbException

getDiskFreeSpace

public long getDiskFreeSpace()
                      throws SmbException

Description copied from interface: SmbResource

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.

Specified by:

getDiskFreeSpace in interface SmbResource

Returns:

the free disk space in bytes of the drive on which this file or directory resides

Throws:

SmbException

mkdir

public void mkdir()
           throws SmbException

Description copied from interface: SmbResource

Creates a directory with the path specified by this SmbResource. For this method to be successful, 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 (although in the future it may be possible to create shares).

Specified by:

mkdir in interface SmbResource

Throws:

SmbException

mkdirs

public void mkdirs()
            throws SmbException

Description copied from interface: SmbResource

Creates a directory with the path specified by this SmbResource and any parent directories that do not 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 (although in the future it may be possible to create shares).

Specified by:

mkdirs in interface SmbResource

Throws:

SmbException

createNewFile

public void createNewFile()
                   throws SmbException

Description copied from interface: SmbResource

Create a new file but fail if it already exists. The check for existence of the file and it's creation are an atomic operation with respect to other filesystem activities.

Specified by:

createNewFile in interface SmbResource

Throws:

SmbException

setFileTimes

public void setFileTimes(long createTime,
                         long lastLastModified,
                         long lastLastAccess)
                  throws SmbException

Description copied from interface: SmbResource

Set the create, last modified and last access time of the file. The time is specified as milliseconds from Jan 1, 1970 which is the same as that which is returned by the createTime(), lastModified(), lastAccess() methods.
This method does not apply to workgroups, servers, or shares.

Specified by:

setFileTimes in interface SmbResource

Parameters:

createTime - the create time as milliseconds since Jan 1, 1970

lastLastModified - the last modified time as milliseconds since Jan 1, 1970

lastLastAccess - the last access time as milliseconds since Jan 1, 1970

Throws:

SmbUnsupportedOperationException - if CAP_NT_SMBS is unavailable

SmbException

See Also:

SmbResource.setCreateTime(long), SmbResource.setLastAccess(long), SmbResource.setLastModified(long)

setCreateTime

public void setCreateTime(long time)
                   throws SmbException

Description copied from interface: SmbResource

Set the create time of the file. The time is specified as milliseconds from Jan 1, 1970 which is the same as that which is returned by the createTime() method.
This method does not apply to workgroups, servers, or shares.

Specified by:

setCreateTime in interface SmbResource

Parameters:

time - the create time as milliseconds since Jan 1, 1970

Throws:

SmbUnsupportedOperationException - if CAP_NT_SMBS is unavailable

SmbException

setLastModified

public void setLastModified(long time)
                     throws SmbException

Description copied from interface: SmbResource

Set the last modified time of the file. The time is specified as milliseconds from Jan 1, 1970 which is the same as that which is returned by the lastModified() method.
This method does not apply to workgroups, servers, or shares.

Specified by:

setLastModified in interface SmbResource

Parameters:

time - the last modified time as milliseconds since Jan 1, 1970

Throws:

SmbException

setLastAccess

public void setLastAccess(long time)
                   throws SmbException

Description copied from interface: SmbResource

Set the last access time of the file. The time is specified as milliseconds from Jan 1, 1970 which is the same as that which is returned by the lastAccess() method.
This method does not apply to workgroups, servers, or shares.

Specified by:

setLastAccess in interface SmbResource

Parameters:

time - the last access time as milliseconds since Jan 1, 1970

Throws:

SmbUnsupportedOperationException - if CAP_NT_SMBS is unavailable

SmbException

getAttributes

public int getAttributes()
                  throws SmbException

Description copied from interface: SmbResource

Return the attributes of this file. Attributes are represented as a bitset that must be masked with ATTR_* constants to determine if they are set or unset. The value returned is suitable for use with the setAttributes() method.

Specified by:

getAttributes in interface SmbResource

Returns:

the ATTR_* attributes associated with this file

Throws:

SmbException

setAttributes

public void setAttributes(int attrs)
                   throws SmbException

Description copied from interface: SmbResource

Set the attributes of this file. Attributes are composed into a bitset by bitwise ORing the ATTR_* constants. Setting the value returned by getAttributes will result in both files having the same attributes.

Specified by:

setAttributes in interface SmbResource

Parameters:

attrs - attribute flags

Throws:

SmbException

setReadOnly

public void setReadOnly()
                 throws SmbException

Description copied from interface: SmbResource

Make this file read-only. This is shorthand for setAttributes( getAttributes() | ATTR_READ_ONLY ).

Specified by:

setReadOnly in interface SmbResource

Throws:

SmbException

setReadWrite

public void setReadWrite()
                  throws SmbException

Description copied from interface: SmbResource

Turn off the read-only attribute of this file. This is shorthand for setAttributes( getAttributes() & ~ATTR_READONLY ).

Specified by:

setReadWrite in interface SmbResource

Throws:

SmbException

toURL

@Deprecated
public URL toURL()

Deprecated. Use getURL() instead

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 (i.e. no doOutput).

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 essence, 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 Object

Returns:

A hashcode for this abstract file

equals

public boolean equals(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 insensitively 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 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 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 URLConnection

Returns:

The original URL representation of this SMB resource

getContentLength

@Deprecated
public int getContentLength()

Deprecated.

This URLConnection method just returns the result of length().

Overrides:

getContentLength in class URLConnection

Returns:

the length of this file or 0 if it refers to a directory

getContentLengthLong

public long getContentLengthLong()

Overrides:

getContentLengthLong in class URLConnection

See Also:

URLConnection.getContentLengthLong()

getDate

public long getDate()

This URLConnection method just returns the result of lastModified.

Overrides:

getDate in class URLConnection

Returns:

the last modified data as milliseconds since Jan 1, 1970

getLastModified

public long getLastModified()

This URLConnection method just returns the result of lastModified.

Overrides:

getLastModified in class URLConnection

Returns:

the last modified data as milliseconds since Jan 1, 1970

getInputStream

public InputStream getInputStream()
                           throws IOException

This URLConnection method just returns a new SmbFileInputStream created with this file.

Overrides:

getInputStream in class URLConnection

Throws:

IOException - thrown by SmbFileInputStream constructor

openInputStream

public SmbFileInputStream openInputStream()
                                   throws SmbException

Description copied from interface: SmbResource

Opens an input stream reading the file (read only, sharable)

Specified by:

openInputStream in interface SmbResource

Returns:

input stream, needs to be closed when finished

Throws:

SmbException

openInputStream

public SmbFileInputStream openInputStream(int sharing)
                                   throws SmbException

Description copied from interface: SmbResource

Opens an input stream reading the file (read only)

Specified by:

openInputStream in interface SmbResource

Parameters:

sharing - flags indicating for which operations others may open the file (FILE_SHARING_*)

Returns:

input stream, needs to be closed when finished

Throws:

SmbException

openInputStream

public SmbFileInputStream openInputStream(int flags,
                                          int access,
                                          int sharing)
                                   throws SmbException

Description copied from interface: SmbResource

Opens an input stream reading the file (read only)

Specified by:

openInputStream in interface SmbResource

Parameters:

flags - open flags

access - desired access flags

sharing - flags indicating for which operations others may open the file (FILE_SHARING_*)

Returns:

input stream, needs to be closed when finished

Throws:

SmbException

getOutputStream

public OutputStream getOutputStream()
                             throws IOException

Overrides:

getOutputStream in class URLConnection

Throws:

IOException

openOutputStream

public SmbFileOutputStream openOutputStream()
                                     throws SmbException

Description copied from interface: SmbResource

Opens an output stream writing to the file (truncating, write only, sharable)

Specified by:

openOutputStream in interface SmbResource

Returns:

output stream, needs to be closed when finished

Throws:

SmbException

openOutputStream

public SmbFileOutputStream openOutputStream(boolean append)
                                     throws SmbException

Description copied from interface: SmbResource

Opens an output stream writing to the file (write only, read sharable)

Specified by:

openOutputStream in interface SmbResource

Parameters:

append - whether to append to or truncate the input

Returns:

output stream, needs to be closed when finished

Throws:

SmbException

openOutputStream

public SmbFileOutputStream openOutputStream(boolean append,
                                            int sharing)
                                     throws SmbException

Description copied from interface: SmbResource

Opens an output stream writing to the file (write only, exclusive write access)

Specified by:

openOutputStream in interface SmbResource

Parameters:

append - whether to append to or truncate the input

sharing - flags indicating for which operations others may open the file (FILE_SHARING_*)

Returns:

output stream, needs to be closed when finished

Throws:

SmbException

openOutputStream

public SmbFileOutputStream openOutputStream(boolean append,
                                            int openFlags,
                                            int access,
                                            int sharing)
                                     throws SmbException

Description copied from interface: SmbResource

Opens an output stream writing to the file (write only, exclusive write access)

Specified by:

openOutputStream in interface SmbResource

Parameters:

append - whether to append to or truncate the input

openFlags - flags for open operation

access - desired file access flags

sharing - flags indicating for which operations others may open the file

Returns:

output stream, needs to be closed when finished

Throws:

SmbException

openRandomAccess

public SmbRandomAccessFile openRandomAccess(String mode)
                                     throws SmbException

Description copied from interface: SmbResource

Opens the file for random access

Specified by:

openRandomAccess in interface SmbResource

Parameters:

mode - access mode (r|rw)

Returns:

random access file, needs to be closed when finished

Throws:

SmbException

openRandomAccess

public SmbRandomAccessFile openRandomAccess(String mode,
                                            int sharing)
                                     throws SmbException

Description copied from interface: SmbResource

Opens the file for random access

Specified by:

openRandomAccess in interface SmbResource

Parameters:

mode - access mode (r|rw)

sharing - flags indicating for which operations others may concurrently open the file

Returns:

random access file, needs to be closed when finished

Throws:

SmbException

fileIndex

public long fileIndex()
               throws SmbException

Description copied from interface: SmbResource

Get the file index

Specified by:

fileIndex in interface SmbResource

Returns:

server side file index, 0 if unavailable

Throws:

SmbException

getSecurity

public ACE[] getSecurity()
                  throws IOException

Description copied from interface: SmbResource

Return an array of Access Control Entry (ACE) objects representing the security descriptor associated with this file or directory.

Initially, the SIDs within each ACE will not be resolved however when getType(), getDomainName(), getAccountName(), or toString() is called, the names will attempt to be resolved. If the names cannot be resolved (e.g. due to temporary network failure), the said methods will return default values (usually S-X-Y-Z strings of fragments of).

Alternatively getSecurity(true) may be used to resolve all SIDs together and detect network failures.

Specified by:

getSecurity in interface SmbResource

Returns:

array of ACEs

Throws:

IOException

getSecurity

public ACE[] getSecurity(boolean resolveSids)
                  throws IOException

Description copied from interface: SmbResource

Return an array of Access Control Entry (ACE) objects representing the security descriptor associated with this file or directory. If no DACL is present, null is returned. If the DACL is empty, an array with 0 elements is returned.

Specified by:

getSecurity in interface SmbResource

Parameters:

resolveSids - Attempt to resolve the SIDs within each ACE form their numeric representation to their corresponding account names.

Returns:

array of ACEs

Throws:

IOException

getOwnerUser

public SID getOwnerUser()
                 throws IOException

Description copied from interface: SmbResource

Return the resolved owner user SID for this file or directory

Specified by:

getOwnerUser in interface SmbResource

Returns:

the owner user SID, null if not present

Throws:

IOException

getOwnerUser

public SID getOwnerUser(boolean resolve)
                 throws IOException

Description copied from interface: SmbResource

Return the owner user SID for this file or directory

Specified by:

getOwnerUser in interface SmbResource

Parameters:

resolve - whether to resolve the user name

Returns:

the owner user SID, null if not present

Throws:

IOException

getOwnerGroup

public SID getOwnerGroup()
                  throws IOException

Description copied from interface: SmbResource

Return the resolved owner group SID for this file or directory

Specified by:

getOwnerGroup in interface SmbResource

Returns:

the owner group SID, null if not present

Throws:

IOException

getOwnerGroup

public SID getOwnerGroup(boolean resolve)
                  throws IOException

Description copied from interface: SmbResource

Return the owner group SID for this file or directory

Specified by:

getOwnerGroup in interface SmbResource

Parameters:

resolve - whether to resolve the group name

Returns:

the owner group SID, null if not present

Throws:

IOException

getShareSecurity

public ACE[] getShareSecurity(boolean resolveSids)
                       throws IOException

Description copied from interface: SmbResource

Return an array of Access Control Entry (ACE) objects representing the share permissions on the share exporting this file or directory. If no DACL is present, null is returned. If the DACL is empty, an array with 0 elements is returned.

Note that this is different from calling getSecurity on a share. There are actually two different ACLs for shares - the ACL on the share and the ACL on the folder being shared. Go to Computer Management > System Tools > Shared Folders > Shares and look at the Properties for a share. You will see two tabs - one for "Share Permissions" and another for "Security". These correspond to the ACLs returned by getShareSecurity and getSecurity respectively.

Specified by:

getShareSecurity in interface SmbResource

Parameters:

resolveSids - Attempt to resolve the SIDs within each ACE form their numeric representation to their corresponding account names.

Returns:

array of ACEs

Throws:

IOException