All those names...
SMB is a protocol used by computers to share resources, such as files and printers, on a network. It is supported by a lot of different operating systems. Most notably, MS Windows supports smb natively.
Samba and libsmbclient
The Samba project develops the Open Source samba suite, which is excellent for people who want their computer to be smb enabled without resorting to proprietary software. Included in samba is a C library called libsmbclient which makes it easier for programmers to access smb resources.
The final step in this abstraction, away from bits and bytes and closer to the thoughts of the programmer, is by entering the dynamic and high-level nature of the Ruby programming language. That's what Ruby/SMB is for.
Working with Ruby/SMB
First (perhaps after reading this through) go to the project download page, download the latest version, unzip and untar it, then follow the instructions in the included INSTALL file.
The SMB module
To use Ruby/SMB in your Ruby program, just do:
This initializes the library, which defines the SMB module. For details on the methods available see Library API. We'll look at some examples here.
Downloading and uploading files
Say that you've got a file "music.mp3" on your friend's computer "Multivac" in a shared called "public". To fetch it and save it on you computer, do the following:
Alternatively, you can use
File.open "music.mp3", "w" do |local|
SMB.open "smb://multivac/public/music.mp3", "r" do |remote|
while data = remote.read(1024)
SMB::File.open instead of the short form
SMB.open. Specifying length to read (1024 in this case) is a good idea since otherwise all the data would be read into memory before writing it to disk.
What if it's you who've got the file and your friend who wants it? Easy! Just change places on those "w" and "r", and change
You can browse the contents of smb network workgroups, servers, shares, and directories. They are all represented by the class
SMB::Dir. Similar to the previous example,
SMB.open can be replaced by
SMB::Dir.open, if that feels more natural to you.
Now, to browse directories (and also workgroups, servers, and file shares, as mentioned above), we do this:
There are many ways of doing this though, so look through the documentation of the
SMB.open "smb://multivac/public/" do |dir|
print dir.url + " contains:\n"
while name = dir.read
print name, "\t"
SMB::Dir class in Library API. To open a workgroup, simply use the url "smb://workgroupname/".
The complete format of a smb url as recognized by Ruby/SMB and libsmbclient is:
Also, smb:// returns a browsing of all workgroups, and smb://name/ can mean both a server name and workgroup name.
SMB::Util module, which is mixed in to
SMB::Dir::Entry parses out the respective parts of the smb url, which is returned by the
url method of the classes mentioned.
Compatibility with Ruby's File and Dir classes
Ruby/SMB aims to be as compatible as possible with Ruby's
Dir classes. They already do a pretty good job at this (if I may say so ;o), especially the
Dir class. Generally, you can assume that the
SMB::File classes work as you're used to, but check the Library API for notes on incompatibilities and incompletenesses of various methods.
Ruby/SMB is still in alpha, and many things will improve in the time to come, especially if you make bug reports and feature requests at the SourceForge project page or by mail.
back to Ruby/SMB home page
Author: Henrik Falck <hefa at users.sourceforge.net>