Module jcifs
Package org.codelibs.jcifs.smb1

Class SmbFile

java.lang.Object
java.net.URLConnection
org.codelibs.jcifs.smb1.SmbFile
Direct Known Subclasses:
SmbNamedPipe
public class SmbFile extends 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 [1] to specify the target file or directory. SmbFile URLs have the following syntax: 
     smb1://[[[domain;]username[:password]@]server[:port]/[[share/[dir/]file]]][?param=value[param2=value2[...]]]
This example: 
     smb1://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 'smb1://' URLs it is necessary to first call the static org.codelibs.jcifs.smb1.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 org.codelibs.jcifs.smb1 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
SMB URL Examples
URLDescription
smb1://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.
smb1://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.
smb1://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.
smb1://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.
smb1:// Just as smb1://server/ lists shares and smb1://workgroup/ lists servers, the smb1:// 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 will always return false).
smb1://angus.foo.net/d/org.codelibs.jcifs.smb/smb1/pipes.doc The server name may also be a DNS name as it is in this example. See Setting Name Resolution Properties for details.
smb1://192.168.1.15/ADMIN$/ The server name may also be an IP address. See Setting Name Resolution Properties for details.
smb1://domain;username:password@server/share/path/to/file.txt A prototypical example that uses all the fields.
smb1://myworkgroup/angus/ <-- ILLEGAL Despite the hierarchial relationship between workgroups, servers, and filesystems this example is not valid.
smb1://server/share/path/to/dir <-- ILLEGAL URLs that represent workgroups, servers, shares, or directories require a trailing slash '/'.
smb1://MYGROUP/?SERVER=192.168.10.15 SMB URLs support some query string parameters. In this example the SERVER parameter is used to override the server name service lookup to contact the server 192.168.10.15 (presumably known to be a master browser) for the server list in workgroup MYGROUP.

A second constructor argument may be specified to augment the URL for better programmatic control when processing many files under a common base. This is slightly different from the corresponding java.io.File usage; a '/' at the beginning of the second parameter will still use the server component of the first parameter. The examples below illustrate the resulting URLs when this second contructor argument is used.

Examples Of SMB URLs When Augmented With A Second Constructor Parameter
Examples Of SMB URLs When Augmented With A Second Constructor Parameter
First ParameterSecond ParameterResult
smb1://host/share/a/b/ c/d/ smb1://host/share/a/b/c/d/
smb1://host/share/foo/bar/ /share2/zig/zag smb1://host/share2/zig/zag
smb1://host/share/foo/bar/ ../zip/ smb1://host/share/foo/zip/
smb1://host/share/zig/zag smb1://foo/bar/ smb1://foo/bar/
smb1://host/share/foo/ ../.././.././../foo/ smb1://host/foo/
smb1://host/share/zig/zag / smb1://host/
smb1://server/ ../ smb1://server/
smb1:// myworkgroup/ smb1://myworkgroup/
smb1://myworkgroup/ angus/ smb1://myworkgroup/angus/ <-- ILLEGAL
(But if you first create an SmbFile with 'smb1://workgroup/' 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:

  • Field Details

    • FILE_NO_SHARE

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

    • 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.
      See Also:

    • 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.
      See Also:

    • 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.
      See Also:

    • ATTR_READONLY

      public static final int ATTR_READONLY
      A file with this bit on as returned by getAttributes() or set with setAttributes() will be read-only
      See Also:

    • ATTR_HIDDEN

      public static final int ATTR_HIDDEN
      A file with this bit on as returned by getAttributes() or set with setAttributes() will be hidden
      See Also:

    • ATTR_SYSTEM

      public static final int ATTR_SYSTEM
      A file with this bit on as returned by getAttributes() or set with setAttributes() will be a system file
      See Also:

    • ATTR_VOLUME

      public static final int ATTR_VOLUME
      A file with this bit on as returned by getAttributes() is a volume
      See Also:

    • ATTR_DIRECTORY

      public static final int ATTR_DIRECTORY
      A file with this bit on as returned by getAttributes() is a directory
      See Also:

    • ATTR_ARCHIVE

      public static final int ATTR_ARCHIVE
      A file with this bit on as returned by getAttributes() or set with setAttributes() is an archived file
      See Also:

    • TYPE_FILESYSTEM

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

    • TYPE_WORKGROUP

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

    • TYPE_SERVER

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

    • TYPE_SHARE

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

    • TYPE_NAMED_PIPE

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

    • TYPE_PRINTER

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

    • TYPE_COMM

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

    • dfs

      protected static Dfs dfs
      DFS resolver instance

    • DEFAULT_PORT

      static final int DEFAULT_PORT
      Default SMB port number
      See Also:

    • DEFAULT_MAX_MPX_COUNT

      static final int DEFAULT_MAX_MPX_COUNT
      Default maximum multiplex count
      See Also:

    • DEFAULT_RESPONSE_TIMEOUT

      static final int DEFAULT_RESPONSE_TIMEOUT
      Default response timeout in milliseconds
      See Also:

    • DEFAULT_SO_TIMEOUT

      static final int DEFAULT_SO_TIMEOUT
      Default socket timeout in milliseconds
      See Also:

    • DEFAULT_RCV_BUF_SIZE

      static final int DEFAULT_RCV_BUF_SIZE
      Default receive buffer size in bytes
      See Also:

    • DEFAULT_SND_BUF_SIZE

      static final int DEFAULT_SND_BUF_SIZE
      Default send buffer size in bytes
      See Also:

    • DEFAULT_SSN_LIMIT

      static final int DEFAULT_SSN_LIMIT
      Default session limit
      See Also:

    • DEFAULT_CONN_TIMEOUT

      static final int DEFAULT_CONN_TIMEOUT
      Default connection timeout in milliseconds
      See Also:

    • LADDR

      static final InetAddress LADDR
      Local address to bind to

    • LPORT

      static final int LPORT
      Local port to bind to

    • MAX_MPX_COUNT

      static final int MAX_MPX_COUNT
      Maximum multiplex count

    • SND_BUF_SIZE

      static final int SND_BUF_SIZE
      Send buffer size in bytes

    • RCV_BUF_SIZE

      static final int RCV_BUF_SIZE
      Receive buffer size in bytes

    • USE_UNICODE

      static final boolean USE_UNICODE
      Whether to use Unicode strings

    • FORCE_UNICODE

      static final boolean FORCE_UNICODE
      Whether to force Unicode usage

    • USE_NTSTATUS

      static final boolean USE_NTSTATUS
      Whether to use NT status codes

    • SIGNPREF

      static final boolean SIGNPREF
      Whether signing is preferred

    • USE_NTSMBS

      static final boolean USE_NTSMBS
      Whether to use NT SMBs

    • USE_EXTSEC

      static final boolean USE_EXTSEC
      Whether to use extended security

    • NETBIOS_HOSTNAME

      static final String NETBIOS_HOSTNAME
      NetBIOS hostname

    • LM_COMPATIBILITY

      static final int LM_COMPATIBILITY
      LM compatibility level

    • FLAGS_NONE

      static final int FLAGS_NONE
      No flags set
      See Also:

    • FLAGS_LOCK_AND_READ_WRITE_AND_UNLOCK

      static final int FLAGS_LOCK_AND_READ_WRITE_AND_UNLOCK
      Lock and read write and unlock flag
      See Also:

    • FLAGS_RECEIVE_BUFFER_POSTED

      static final int FLAGS_RECEIVE_BUFFER_POSTED
      Receive buffer posted flag
      See Also:

    • FLAGS_PATH_NAMES_CASELESS

      static final int FLAGS_PATH_NAMES_CASELESS
      Path names are caseless flag
      See Also:

    • FLAGS_PATH_NAMES_CANONICALIZED

      static final int FLAGS_PATH_NAMES_CANONICALIZED
      Path names canonicalized flag
      See Also:

    • FLAGS_OPLOCK_REQUESTED_OR_GRANTED

      static final int FLAGS_OPLOCK_REQUESTED_OR_GRANTED
      Oplock requested or granted flag
      See Also:

    • FLAGS_NOTIFY_OF_MODIFY_ACTION

      static final int FLAGS_NOTIFY_OF_MODIFY_ACTION
      Notify of modify action flag
      See Also:

    • FLAGS_RESPONSE

      static final int FLAGS_RESPONSE
      Response flag
      See Also:

    • FLAGS2_NONE

      static final int FLAGS2_NONE
      No flags2 set
      See Also:

    • FLAGS2_LONG_FILENAMES

      static final int FLAGS2_LONG_FILENAMES
      Long filenames supported flag
      See Also:

    • FLAGS2_EXTENDED_ATTRIBUTES

      static final int FLAGS2_EXTENDED_ATTRIBUTES
      Extended attributes supported flag
      See Also:

    • FLAGS2_SECURITY_SIGNATURES

      static final int FLAGS2_SECURITY_SIGNATURES
      Security signatures supported flag
      See Also:

    • FLAGS2_EXTENDED_SECURITY_NEGOTIATION

      static final int FLAGS2_EXTENDED_SECURITY_NEGOTIATION
      Extended security negotiation flag
      See Also:

    • FLAGS2_RESOLVE_PATHS_IN_DFS

      static final int FLAGS2_RESOLVE_PATHS_IN_DFS
      Resolve paths in DFS flag
      See Also:

    • FLAGS2_PERMIT_READ_IF_EXECUTE_PERM

      static final int FLAGS2_PERMIT_READ_IF_EXECUTE_PERM
      Permit read if execute permission flag
      See Also:

    • FLAGS2_STATUS32

      static final int FLAGS2_STATUS32
      32-bit status codes flag
      See Also:

    • FLAGS2_UNICODE

      static final int FLAGS2_UNICODE
      Unicode strings flag
      See Also:

    • CAP_NONE

      static final int CAP_NONE
      No capabilities
      See Also:

    • CAP_RAW_MODE

      static final int CAP_RAW_MODE
      Raw mode capability
      See Also:

    • CAP_MPX_MODE

      static final int CAP_MPX_MODE
      MPX mode capability
      See Also:

    • CAP_UNICODE

      static final int CAP_UNICODE
      Unicode capability
      See Also:

    • CAP_LARGE_FILES

      static final int CAP_LARGE_FILES
      Large files capability
      See Also:

    • CAP_NT_SMBS

      static final int CAP_NT_SMBS
      NT SMBs capability
      See Also:

    • CAP_RPC_REMOTE_APIS

      static final int CAP_RPC_REMOTE_APIS
      RPC remote APIs capability
      See Also:

    • CAP_STATUS32

      static final int CAP_STATUS32
      32-bit status codes capability
      See Also:

    • CAP_LEVEL_II_OPLOCKS

      static final int CAP_LEVEL_II_OPLOCKS
      Level II oplocks capability
      See Also:

    • CAP_LOCK_AND_READ

      static final int CAP_LOCK_AND_READ
      Lock and read capability
      See Also:

    • CAP_NT_FIND

      static final int CAP_NT_FIND
      NT find capability
      See Also:

    • CAP_DFS

      static final int CAP_DFS
      DFS capability
      See Also:

    • CAP_EXTENDED_SECURITY

      static final int CAP_EXTENDED_SECURITY
      Extended security capability
      See Also:

    • FILE_READ_DATA

      static final int FILE_READ_DATA
      File read data access right
      See Also:

    • FILE_WRITE_DATA

      static final int FILE_WRITE_DATA
      File write data access right
      See Also:

    • FILE_APPEND_DATA

      static final int FILE_APPEND_DATA
      File append data access right
      See Also:

    • FILE_READ_EA

      static final int FILE_READ_EA
      File read extended attributes access right
      See Also:

    • FILE_WRITE_EA

      static final int FILE_WRITE_EA
      File write extended attributes access right
      See Also:

    • FILE_EXECUTE

      static final int FILE_EXECUTE
      File execute access right
      See Also:

    • FILE_DELETE

      static final int FILE_DELETE
      File delete child access right
      See Also:

    • FILE_READ_ATTRIBUTES

      static final int FILE_READ_ATTRIBUTES
      File read attributes access right
      See Also:

    • FILE_WRITE_ATTRIBUTES

      static final int FILE_WRITE_ATTRIBUTES
      File write attributes access right
      See Also:

    • DELETE

      static final int DELETE
      Delete access right
      See Also:

    • READ_CONTROL

      static final int READ_CONTROL
      Read control access right
      See Also:

    • WRITE_DAC

      static final int WRITE_DAC
      Write DAC access right
      See Also:

    • WRITE_OWNER

      static final int WRITE_OWNER
      Write owner access right
      See Also:

    • SYNCHRONIZE

      static final int SYNCHRONIZE
      Synchronize access right
      See Also:

    • GENERIC_ALL

      static final int GENERIC_ALL
      Generic all access right
      See Also:

    • GENERIC_EXECUTE

      static final int GENERIC_EXECUTE
      Generic execute access right
      See Also:

    • GENERIC_WRITE

      static final int GENERIC_WRITE
      Generic write access right
      See Also:

    • GENERIC_READ

      static final int GENERIC_READ
      Generic read access right
      See Also:

    • FLAGS_TARGET_MUST_BE_FILE

      static final int FLAGS_TARGET_MUST_BE_FILE
      Target must be file flag
      See Also:

    • FLAGS_TARGET_MUST_BE_DIRECTORY

      static final int FLAGS_TARGET_MUST_BE_DIRECTORY
      Target must be directory flag
      See Also:

    • FLAGS_COPY_TARGET_MODE_ASCII

      static final int FLAGS_COPY_TARGET_MODE_ASCII
      Copy target mode ASCII flag
      See Also:

    • FLAGS_COPY_SOURCE_MODE_ASCII

      static final int FLAGS_COPY_SOURCE_MODE_ASCII
      Copy source mode ASCII flag
      See Also:

    • FLAGS_VERIFY_ALL_WRITES

      static final int FLAGS_VERIFY_ALL_WRITES
      Verify all writes flag
      See Also:

    • FLAGS_TREE_COPY

      static final int FLAGS_TREE_COPY
      Tree copy flag
      See Also:

    • OPEN_FUNCTION_FAIL_IF_EXISTS

      static final int OPEN_FUNCTION_FAIL_IF_EXISTS
      Open function fail if exists
      See Also:

    • OPEN_FUNCTION_OVERWRITE_IF_EXISTS

      static final int OPEN_FUNCTION_OVERWRITE_IF_EXISTS
      Open function overwrite if exists
      See Also:

    • PID

      static final int PID
      Process ID

    • SECURITY_SHARE

      static final int SECURITY_SHARE
      Share level security
      See Also:

    • SECURITY_USER

      static final int SECURITY_USER
      User level security
      See Also:

    • CMD_OFFSET

      static final int CMD_OFFSET
      Command offset in SMB header
      See Also:

    • ERROR_CODE_OFFSET

      static final int ERROR_CODE_OFFSET
      Error code offset in SMB header
      See Also:

    • FLAGS_OFFSET

      static final int FLAGS_OFFSET
      Flags offset in SMB header
      See Also:

    • SIGNATURE_OFFSET

      static final int SIGNATURE_OFFSET
      Signature offset in SMB header
      See Also:

    • TID_OFFSET

      static final int TID_OFFSET
      TID offset in SMB header
      See Also:

    • HEADER_LENGTH

      static final int HEADER_LENGTH
      SMB header length
      See Also:

    • MILLISECONDS_BETWEEN_1970_AND_1601

      static final long MILLISECONDS_BETWEEN_1970_AND_1601
      Milliseconds between 1970 and 1601
      See Also:

    • TZ

      static final TimeZone TZ
      Default timezone

    • USE_BATCHING

      static final boolean USE_BATCHING
      Whether to use batching

    • OEM_ENCODING

      static final String OEM_ENCODING
      OEM encoding

    • UNI_ENCODING

      static final String UNI_ENCODING
      Unicode encoding
      See Also:

    • DEFAULT_FLAGS2

      static final int DEFAULT_FLAGS2
      Default FLAGS2 value

    • DEFAULT_CAPABILITIES

      static final int DEFAULT_CAPABILITIES
      Default capabilities

    • FLAGS2

      static final int FLAGS2
      FLAGS2 value

    • CAPABILITIES

      static final int CAPABILITIES
      Capabilities value

    • TCP_NODELAY

      static final boolean TCP_NODELAY
      Whether to use TCP_NODELAY

    • RESPONSE_TIMEOUT

      static final int RESPONSE_TIMEOUT
      Response timeout in milliseconds

    • CONNECTIONS

      static final LinkedList CONNECTIONS
      List of active connections

    • SSN_LIMIT

      static final int SSN_LIMIT
      Session limit

    • SO_TIMEOUT

      static final int SO_TIMEOUT
      Socket timeout in milliseconds

    • CONN_TIMEOUT

      static final int CONN_TIMEOUT
      Connection timeout in milliseconds

    • NATIVE_OS

      static final String NATIVE_OS
      Native operating system name

    • NATIVE_LANMAN

      static final String NATIVE_LANMAN
      Native LAN manager name

    • VC_NUMBER

      static final int VC_NUMBER
      Virtual circuit number
      See Also:

    • NULL_TRANSPORT

      static final SmbTransport NULL_TRANSPORT
      Null transport instance

  • Constructor Details

    • SmbFile

      public SmbFile(String url) throws 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:
      MalformedURLException - If the parent and child parameters do not follow the prescribed syntax

    • SmbFile

      public SmbFile(SmbFile 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 paremeter
      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 context, String name) throws 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:
      MalformedURLException - If the context and name parameters do not follow the prescribed syntax

    • SmbFile

      public SmbFile(String url, NtlmPasswordAuthentication auth) throws MalformedURLException
      Constructs an SmbFile representing a resource on an SMB network such as a file or directory.
      Parameters:
      url - A URL string
      auth - The credentials the client should use for authentication
      Throws:
      MalformedURLException - If the url parameter does not follow the prescribed syntax

    • SmbFile

      public SmbFile(String url, NtlmPasswordAuthentication auth, int shareAccess) throws MalformedURLException
      Constructs an SmbFile representing a file on an SMB network. 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:
      MalformedURLException - If the url parameter does not follow the prescribed syntax

    • SmbFile

      public SmbFile(String context, String name, NtlmPasswordAuthentication auth) throws 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.
      Parameters:
      context - A URL string
      name - A path string relative to the context paremeter
      auth - The credentials the client should use for authentication
      Throws:
      MalformedURLException - If the context and name parameters do not follow the prescribed syntax

    • SmbFile

      public SmbFile(String context, String name, NtlmPasswordAuthentication auth, int shareAccess) throws 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 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:
      MalformedURLException - If the context and name parameters do not follow the prescribed syntax

    • SmbFile

      public SmbFile(SmbFile context, String name, int shareAccess) 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 context. See the description above for examples of using the second name parameter. 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 base SmbFile
      name - A path string relative to the context file path
      shareAccess - Specifies what access other clients have while this file is open.
      Throws:
      MalformedURLException - If the context and name parameters do not follow the prescribed syntax
      UnknownHostException - if the server cannot be resolved

    • SmbFile

      public SmbFile(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(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.
      Parameters:
      url - The URL of the target resource
      auth - The credentials the client should use for authentication

  • Method Details

    • connect

      public void connect() throws IOException
      It is not necessary to call this method directly. This is the URLConnection implementation of connect().
      Specified by:
      connect in class URLConnection
      Throws:
      IOException

    • getPrincipal

      public Principal getPrincipal()
      Returns the principal used for authentication
      Returns:
      the authentication principal

    • getName

      public 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 smb1:// is also smb1://. 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.
      Returns:
      The last component of the URL associated with this SMB resource or smb1:// if the resource is smb1:// itself.

    • getParent

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

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

    • getUncPath

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

    • 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 smb1://, smb1://workgroup/, and smb1://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 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 smb1:// 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.
      Throws:
      SmbException - if an error occurs while determining the type

    • 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 smb1:// 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
      Throws:
      SmbException - if an error occurs while checking existence

    • 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
      Throws:
      SmbException - if an error occurs while checking read permissions

    • 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 smb1://, smb1://workgroup/, and smb1://server/ resources will be read-only.
      Returns:
      true if the resource exists is not marked read-only
      Throws:
      SmbException - if an error occurs while checking write permissions

    • 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
      Throws:
      SmbException - if an error occurs while checking if this 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
      Throws:
      SmbException - if an error occurs while checking if this is a file

    • isHidden

      public boolean isHidden() throws SmbException
      Tests to see if the file this SmbFile represents is marked as hidden. This method will also return true for shares with names that end with '$' such as IPC$ or C$.
      Returns:
      true if the SmbFile is marked as being hidden
      Throws:
      SmbException - if an error occurs while checking if this is hidden

    • getDfsPath

      public String getDfsPath() throws SmbException
      Returns the DFS path for this file if it resides in a DFS share
      Returns:
      the DFS path or null if not in DFS
      Throws:
      SmbException - if an error occurs while resolving the DFS path

    • createTime

      public long createTime() throws SmbException
      Retrieve the time this SmbFile 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.
      Returns:
      The number of milliseconds since the 00:00:00 GMT, January 1, 1970 as a long value
      Throws:
      SmbException - if an error occurs while retrieving the creation time

    • 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 (i.e. seconds since Epoch 1970). 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
      Throws:
      SmbException - if an error occurs while retrieving the last modified time

    • 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 smb1://,
      • all servers registered as members of a NetBIOS workgroup if this resource refers to a workgroup in a smb1://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 smb1://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 - if an error occurs while listing the contents

    • 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:
      An array of filenames
      Throws:
      SmbException - if an error occurs while listing the contents

    • 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 smb1://,
      • all servers registered as members of a NetBIOS workgroup if this resource refers to a workgroup in a smb1://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 smb1://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
      Throws:
      SmbException - if an error occurs while listing the files

    • 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
      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 - if an error occurs while listing the files

    • 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.
      Parameters:
      filter - a filter to exclude files from the results
      Returns:
      An array of SmbFile objects
      Throws:
      SmbException - if an error occurs while listing the files

    • 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.
      Parameters:
      filter - a file filter to exclude files from the results
      Returns:
      An array of SmbFile objects
      Throws:
      SmbException - if an error occurs while listing the files

    • 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). To access the renamed file it is necessary to construct a new SmbFile.
      Parameters:
      dest - An SmbFile that represents the new pathname
      Throws:
      NullPointerException - If the dest argument is null
      SmbException - if an error occurs during the rename operation

    • copyTo

      public void copyTo(SmbFile dest) throws SmbException
      This method will copy the file or directory represented by this SmbFile 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 attibutes 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.
      Parameters:
      dest - the destination file or directory
      Throws:
      SmbException - if an error occurs during the copy operation

    • 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 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.
      Throws:
      SmbException - if an error occurs while deleting the file or directory

    • 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.
      Throws:
      SmbException - if an error occurs while retrieving the file length

    • 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.
      Returns:
      the free disk space in bytes of the drive on which this file or directory resides
      Throws:
      SmbException - if an error occurs while retrieving disk space information

    • mkdir

      public void mkdir() throws SmbException
      Creates a directory with the path specified by this SmbFile. For this method to be successful, the target must not already exist. This method will fail when used with smb1://, smb1://workgroup/, smb1://server/, or smb1://server/share/ URLs because workgroups, servers, and shares cannot be dynamically created (although in the future it may be possible to create shares).
      Throws:
      SmbException - if an error occurs while creating the directory

    • mkdirs

      public void mkdirs() throws SmbException
      Creates a directory with the path specified by this SmbFile and any parent directories that do not exist. This method will fail when used with smb1://, smb1://workgroup/, smb1://server/, or smb1://server/share/ URLs because workgroups, servers, and shares cannot be dynamically created (although in the future it may be possible to create shares).
      Throws:
      SmbException - if an error occurs while creating the directories

    • createNewFile

      public void createNewFile() throws SmbException
      Create a new file but fail if it already exists. The check for existance of the file and it's creation are an atomic operation with respect to other filesystem activities.
      Throws:
      SmbException - if an error occurs while creating the file

    • setCreateTime

      public void setCreateTime(long time) throws SmbException
      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.
      Parameters:
      time - the create time as milliseconds since Jan 1, 1970
      Throws:
      SmbException - if an error occurs while setting the create time

    • setLastModified

      public void setLastModified(long time) throws SmbException
      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(), getLastModified(), and getDate() methods. This method does not apply to workgroups, servers, or shares.
      Parameters:
      time - the last modified time as milliseconds since Jan 1, 1970
      Throws:
      SmbException - if an error occurs while setting the last modified time

    • getAttributes

      public int getAttributes() throws SmbException
      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.
      Returns:
      the ATTR_* attributes associated with this file
      Throws:
      SmbException - if an error occurs while retrieving attributes

    • setAttributes

      public void setAttributes(int attrs) throws SmbException
      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.
      Parameters:
      attrs - the attributes to set
      Throws:
      SmbException - if an error occurs while setting attributes

    • setReadOnly

      public void setReadOnly() throws SmbException
      Make this file read-only. This is shorthand for setAttributes( getAttributes() | ATTR_READ_ONLY ).
      Throws:
      SmbException - if an error occurs while setting the read-only flag

    • setReadWrite

      public void setReadWrite() throws SmbException
      Turn off the read-only attribute of this file. This is shorthand for setAttributes( getAttributes() &amp; ~ATTR_READONLY ).
      Throws:
      SmbException - if an error occurs while clearing the read-only flag

    • toURL

      @Deprecated public URL toURL() throws MalformedURLException
      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
      Throws:
      MalformedURLException - if the URL is malformed

    • 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 Object
      Returns:
      A hashcode for this abstract file

    • pathNamesPossiblyEqual

      protected boolean pathNamesPossiblyEqual(String path1, String path2)
      Checks if two path names could possibly be equal
      Parameters:
      path1 - the first path
      path2 - the second path
      Returns:
      true if the paths could be equal

    • 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 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. 
       smb1://192.168.1.15/share/DIR/foo.txt
 smb1://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

      public int getContentLength()
      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

    • 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

    • getOutputStream

      public OutputStream getOutputStream() throws IOException
      This URLConnection method just returns a new SmbFileOutputStream created with this file.
      Overrides:
      getOutputStream in class URLConnection
      Throws:
      IOException - thrown by SmbFileOutputStream constructor

    • getSecurity

      public ACE[] getSecurity(boolean resolveSids) throws IOException
      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.
      Parameters:
      resolveSids - Attempt to resolve the SIDs within each ACE from their numeric representation to their corresponding account names.
      Returns:
      an array of ACE entries for this file
      Throws:
      IOException - if an I/O error occurs

    • getShareSecurity

      public ACE[] getShareSecurity(boolean resolveSids) throws IOException
      Returns the share security information for this share
      Parameters:
      resolveSids - whether to resolve SIDs to names
      Returns:
      an array of ACE entries for this share
      Throws:
      IOException - if an I/O error occurs

    • getSecurity

      public ACE[] getSecurity() throws IOException
      Returns the security information for this file
      Returns:
      an array of ACE entries for this file
      Throws:
      IOException - if an I/O error occurs

    • getOwnerUser

      public SID getOwnerUser() throws IOException
      Returns the owner user SID for this file
      Returns:
      the owner user SID
      Throws:
      IOException - if an I/O error occurs

    • getOwnerGroup

      public SID getOwnerGroup() throws IOException
      Returns the owner group SID for this file
      Returns:
      the owner group SID
      Throws:
      IOException - if an I/O error occurs