Yet Another SMB URL Syntax

[Michael B. Allen]

Chris and friends have had a little side discussion on the SMB URL syntax;
he is writing an IETF draft on the topic. During the course of things
I thought workgroups might be handled differently so I scribbled down
yet another scheme. It is not really that different from what has been
discussed previously on this list, except in how workgroups are handled;
smb:// lists servers of a 'preferred workgroup' and 'smb://..' lists
all available workgroups. Chris didn't have much to say about it and I'm
not sure what I think but it seems to make good sense so I am submitting
it here for comments.

BTW: The jCIFS project has implemented the *previously described* SMB
URL syntax in full. The SmbShell example program that comes with the
jcifs-0.5dev1 archive allows one to 'cd' around workgroups, shares,
and servers. Kinda neat, requires Java 2.

Thanks,
Mike
http://jcifs.samba.org

Yet Another SMB URL Syntax

The semantics of using workgroups within an smb:// URL is
problematic. There's no doubt about that. The tragedy is that workgroups
are rarely used in this context; they are only useful for "browsing"
with shell interfaces. And yet we must corrupt the URL syntax and our
code to support it. For this reason I would like to purpose yet another
smb:// URL syntax.

The key principle is to push the handling of workgroups out of the
scheme as much as possible by shifting the meaning of components up
the hierarchy but in a way that still provides for the listing of all
available workgroups. This is accomplished by, at first conceptually,
stating clearly that there are *two* separate scheme levels; one to
support the most common and intuitive usage, and the other to add support
for workgroups.

The Level 1 Scheme

The level 1 scheme accommodates the most common usage of smb:// URLs
which would be within configuration files, as an argument to a program,
or similar to address an SMB resource.

Level 1 Syntax:

smb://[[domain;]username[:password]@]server/share/path

This simple syntax would support most users needs. However, it is
widely anticipated that the ability to enumerate files and even shares
of a server should be enabled by making the path and share components
optional. Thus we just add brackets to get:

smb://[[domain;]username[:password]@]server[/share[/path]]

As a result of leaving off these components the following would:

smb://server          enumerate shares
smb://server/share    enumerate directories and files

One major problem with supporting workgroups is shell oriented behavior
and the semantics of relative URL manipulation. For example one might
traverse the resource hierarchy like:

smb://server       + share --> smb://server/share
smb://server/share + path  --> smb://server/share/path

and back up with:

smb://server/share/path + .. --> smb://server/share
smb://server/share      + .. --> smb://server
smb://server            + .. --> smb://server

Note this last traversal would reach the root because smb:// alone is
an illegal level 1 scheme URL.

The Level 2 Scheme

The level 2 smb:// URL scheme provides for the usage of workgroups to
list the servers of a workgroup and all accessible workgroups of the
network (much like the popular "Network Neighborhood" shell interface
does). To ease the transition from the level 1 scheme to the level 2
scheme a hidden 'workgroup' parameter is employed. This parameter may
be NULL or it may be initialized to the hosts preferred workgroup.

Level 2 Syntax:

The level 2 syntax is broken into two specifications to improve
readability and emphasize the separation of workgroups from the level
1 scheme. This first specification looks much like the level 1 syntax
however makes the server component optional.

smb://[[[domain;]username[:password]@]server[/share[/path]]]

Leaving off components now has the following behavior:

smb://server          enumerate shares
smb://                enumerate servers of the preferred workgroup

The second specification is simply:

smb://[workgroup]

Notice this overloads the server component (programmatically this requires
querying for both the 0x20 and 0x1D names, preferably concurrently,
to determine if the component is a server or a workgroup). This usage
of workgroup should:

smb://workgroup       enumerate servers of the workgroup

This begs the question of how to enumerate all available workgroups? The
answer is:

smb://..

So the problematic listing of workgroups has been pushed out of the
equation above the root of the URL hierarchy effectively shifting
everything up to be more congruent with traditional URL semantics. Notice
smb:// more naturally lists servers of the preferred workgroup rather
than workgroups. To be complete, if the preferred workgroup property is
NULL, both smb://.. and smb:// will list all available workgroups.

Traversing the level 2 scheme hierarchy is as follows:

smb://          + server    --> smb://server
smb://          + workgroup --> smb://workgroup
smb://workgroup + server    --> smb://server
smb://server    + share     --> smb://server/share

and back up with:

smb://server/share + .. --> smb://server
smb://server       + .. --> smb://
smb://             + .. --> smb://.. -canonicalize-> smb://

Notice this last case is contextual. It is determined during
canonicalization that the intention is to list all available
workgroups. In this way the smb://.. URL reduces to the case as well.