smbfile.java

实现网上邻居需要的jar库；可以使用库中的接口实现文件共享的功能

/* jcifs smb client library in Java
 * Copyright (C) 2000  "Michael B. Allen" <jcifs at samba dot org>
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

package jcifs.smb;

import java.net.URLConnection;
import java.net.URL;
import java.net.MalformedURLException;
import java.net.UnknownHostException;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.Iterator;
import java.security.Principal;
import jcifs.Config;
import jcifs.util.LogStream;
import jcifs.UniAddress;
import jcifs.netbios.NbtAddress;
import jcifs.dcerpc.*;
import jcifs.dcerpc.msrpc.*;

import java.util.Date;

/**
 * This class represents a resource on an SMB network. Mainly these
 * resources are files and directories however an <code>SmbFile</code>
 * may also refer to servers and workgroups. If the resource is a file or
 * directory the methods of <code>SmbFile</code> follow the behavior of
 * the well known {@link java.io.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:
 *
 * <blockquote><pre>
 *     smb://[[[domain;]username[:password]@]server[:port]/[[share/[dir/]file]]][?[param=value[param2=value2[...]]]
 * </pre></blockquote>
 *
 * This example:
 *
 * <blockquote><pre>
 *     smb://storage15/public/foo.txt
 * </pre></blockquote>
 *
 * would reference the file <code>foo.txt</code> in the share
 * <code>public</code> on the server <code>storage15</code>. In addition
 * to referencing files and directories, jCIFS can also address servers,
 * and workgroups.
 * <p>
 * <font color="#800000"><i>Important: all SMB URLs that represent
 * workgroups, servers, shares, or directories require a trailing slash '/'.
 * </i></font>
 * <p>
 * When using the <tt>java.net.URL</tt> class with
 * 'smb://' URLs it is necessary to first call the static
 * <tt>jcifs.Config.registerSmbURLHandler();</tt> method. This is required
 * to register the SMB protocol handler.
 * <p>
 * The userinfo component of the SMB URL (<tt>domain;user:pass</tt>) 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.
 * <p>
 * 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 <a href="../../../resolver.html">Setting Name
 * Resolution Properties</a>). 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 <a href="../../overview-summary.html#scp">Setting
 * JCIFS Properties</a>). Here are some examples of SMB URLs with brief
 * descriptions of what they do:
 *
 * <p>[1] This URL scheme is based largely on the <i>SMB
 * Filesharing URL Scheme</i> IETF draft.
 * 
 * <p><table border="1" cellpadding="3" cellspacing="0" width="100%">
 * <tr bgcolor="#ccccff">
 * <td colspan="2"><b>SMB URL Examples</b></td>
 * <tr><td width="20%"><b>URL</b></td><td><b>Description</b></td></tr>
 * 
 * <tr><td width="20%"><code>smb://users-nyc;miallen:mypass@angus/tmp/</code></td><td>
 * This URL references a share called <code>tmp</code> on the server
 * <code>angus</code> as user <code>miallen</code> who's password is
 * <code>mypass</code>.
 * </td></tr>
 * 
 * <tr><td width="20%">
 * <code>smb://Administrator:P%40ss@msmith1/c/WINDOWS/Desktop/foo.txt</code></td><td>
 * A relativly sophisticated example that references a file
 * <code>msmith1</code>'s desktop as user <code>Administrator</code>. Notice the '@' is URL encoded with the '%40' hexcode escape.
 * </td></tr>
 * 
 * <tr><td width="20%"><code>smb://angus/</code></td><td>
 * This references only a server. The behavior of some methods is different
 * in this context(e.g. you cannot <code>delete</code> a server) however
 * as you might expect the <code>list</code> method will list the available
 * shares on this server.
 * </td></tr>
 * 
 * <tr><td width="20%"><code>smb://myworkgroup/</code></td><td>
 * This syntactically is identical to the above example. However if
 * <code>myworkgroup</code> happends to be a workgroup(which is indeed
 * suggested by the name) the <code>list</code> method will return
 * a list of servers that have registered themselves as members of
 * <code>myworkgroup</code>.
 * </td></tr>
 * 
 * <tr><td width="20%"><code>smb://</code></td><td>
 * Just as <code>smb://server/</code> lists shares and
 * <code>smb://workgroup/</code> lists servers, the <code>smb://</code>
 * URL lists all available workgroups on a netbios LAN. Again,
 * in this context many methods are not valid and return default
 * values(e.g. <code>isHidden</code> will always return false).
 * </td></tr>
 * 
 * <tr><td width="20%"><code>smb://angus.foo.net/d/jcifs/pipes.doc</code></td><td>
 * The server name may also be a DNS name as it is in this example. See
 * <a href="../../../resolver.html">Setting Name Resolution Properties</a>
 * for details.
 * </td></tr>
 * 
 * <tr><td width="20%"><code>smb://192.168.1.15/ADMIN$/</code></td><td>
 * The server name may also be an IP address. See <a
 * href="../../../resolver.html">Setting Name Resolution Properties</a>
 * for details.
 * </td></tr>
 * 
 * <tr><td width="20%">
 * <code>smb://domain;username:password@server/share/path/to/file.txt</code></td><td>
 * A prototypical example that uses all the fields.
 * </td></tr>
 * 
 * <tr><td width="20%"><code>smb://myworkgroup/angus/ &lt;-- ILLEGAL </code></td><td>
 * Despite the hierarchial relationship between workgroups, servers, and
 * filesystems this example is not valid.
 * </td></tr>
 *
 * <tr><td width="20%">
 * <code>smb://server/share/path/to/dir &lt;-- ILLEGAL </code></td><td>
 * URLs that represent workgroups, servers, shares, or directories require a trailing slash '/'.
 * </td></tr>
 *
 * <tr><td width="20%">
 * <code>smb://MYGROUP/?SERVER=192.168.10.15</code></td><td>
 * SMB URLs support some query string parameters. In this example
 * the <code>SERVER</code> 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 <code>MYGROUP</code>.
 * </td></tr>
 *
 * </table>
 * 
 * <p>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
 * <code>java.io.File</code> 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.
 *
 * <p><table border="1" cellpadding="3" cellspacing="0" width="100%">
 * <tr bgcolor="#ccccff">
 * <td colspan="3">
 * <b>Examples Of SMB URLs When Augmented With A Second Constructor Parameter</b></td>
 * <tr><td width="20%">
 * <b>First Parameter</b></td><td><b>Second Parameter</b></td><td><b>Result</b></td></tr>
 *
 * <tr><td width="20%"><code>
 *  smb://host/share/a/b/
 * </code></td><td width="20%"><code>
 *  c/d/
 * </code></td><td><code>
 *  smb://host/share/a/b/c/d/
 * </code></td></tr>
 * 
 * <tr><td width="20%"><code>
 *  smb://host/share/foo/bar/
 * </code></td><td width="20%"><code>
 *  /share2/zig/zag
 * </code></td><td><code>
 *  smb://host/share2/zig/zag
 * </code></td></tr>
 * 
 * <tr><td width="20%"><code>
 *  smb://host/share/foo/bar/
 * </code></td><td width="20%"><code>
 *  ../zip/
 * </code></td><td><code>
 *  smb://host/share/foo/zip/
 * </code></td></tr>
 * 
 * <tr><td width="20%"><code>
 *  smb://host/share/zig/zag
 * </code></td><td width="20%"><code>
 *  smb://foo/bar/
 * </code></td><td><code>
 *  smb://foo/bar/
 * </code></td></tr>
 * 
 * <tr><td width="20%"><code>
 *  smb://host/share/foo/
 * </code></td><td width="20%"><code>
 *  ../.././.././../foo/
 * </code></td><td><code>
 *  smb://host/foo/
 * </code></td></tr>
 * 
 * <tr><td width="20%"><code>
 *  smb://host/share/zig/zag
 * </code></td><td width="20%"><code>
 *  /
 * </code></td><td><code>
 *  smb://host/
 * </code></td></tr>
 * 
 * <tr><td width="20%"><code>
 *  smb://server/
 * </code></td><td width="20%"><code>
 *  ../
 * </code></td><td><code>
 *  smb://server/
 * </code></td></tr>
 * 
 * <tr><td width="20%"><code>
 *  smb://
 * </code></td><td width="20%"><code>
 *  myworkgroup/
 * </code></td><td><code>
 *  smb://myworkgroup/
 * </code></td></tr>
 * 
 * <tr><td width="20%"><code>
 *  smb://myworkgroup/
 * </code></td><td width="20%"><code>
 *  angus/
 * </code></td><td><code>
 *  smb://myworkgroup/angus/ &lt;-- ILLEGAL<br>(But if you first create an <tt>SmbFile</tt> with 'smb://workgroup/' and use and use it as the first parameter to a constructor that accepts it with a second <tt>String</tt> parameter jCIFS will factor out the 'workgroup'.)
 * </code></td></tr>
 * 
 * </table>
 *
 * <p>Instances of the <code>SmbFile</code> class are immutable; that is,
 * once created, the abstract pathname represented by an SmbFile object
 * will never change.
 *
 * @see       java.io.File
 */

public class SmbFile extends URLConnection implements SmbConstants {

    static final int O_RDONLY = 0x01;
    static final int O_WRONLY = 0x02;
    static final int O_RDWR   = 0x03;
    static final int O_APPEND = 0x04;

    // Open Function Encoding
    // create if the file does not exist
    static final int O_CREAT  = 0x0010;
    // fail if the file exists
    static final int O_EXCL   = 0x0020;
    // truncate if the file exists
    static final int O_TRUNC  = 0x0040;

    // share access
/**
 * When specified as the <tt>shareAccess</tt> 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.
 */
    public static final int FILE_NO_SHARE     = 0x00;
/**
 * When specified as the <tt>shareAccess</tt> 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.
 */
    public static final int FILE_SHARE_READ   = 0x01;
/**
 * When specified as the <tt>shareAccess</tt> 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.
 */
    public static final int FILE_SHARE_WRITE  = 0x02;
/**
 * When specified as the <tt>shareAccess</tt> 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.
 */
    public static final int FILE_SHARE_DELETE = 0x04;

    // file attribute encoding
/** 
 * A file with this bit on as returned by <tt>getAttributes()</tt> or set
 * with <tt>setAttributes()</tt> will be read-only
 */ 
    public static final int ATTR_READONLY   = 0x01;
/** 
 * A file with this bit on as returned by <tt>getAttributes()</tt> or set
 * with <tt>setAttributes()</tt> will be hidden
 */
    public static final int ATTR_HIDDEN     = 0x02;
/**
 * A file with this bit on as returned by <tt>getAttributes()</tt> or set
 * with <tt>setAttributes()</tt> will be a system file
 */
    public static final int ATTR_SYSTEM     = 0x04;
/**
 * A file with this bit on as returned by <tt>getAttributes()</tt> is
 * a volume
 */
    public static final int ATTR_VOLUME     = 0x08;
/**
 * A file with this bit on as returned by <tt>getAttributes()</tt> is
 * a directory
 */
    public static final int ATTR_DIRECTORY  = 0x10;
/**
 * A file with this bit on as returned by <tt>getAttributes()</tt> or set
 * with <tt>setAttributes()</tt> is an archived file
 */
    public static final int ATTR_ARCHIVE    = 0x20;