Prev: Module msg: Generic Message Access

Module obex: Object Exchange Client

This module supports sending and receiving of files via OBEX (Object Exchange) over a Bluetooth®link. The module provides the client side; most Bluetooth equipped devices have an OBEX server which can accept files (put operation of the client); some servers can also deliver files (get operation of the client).

See also module bt.

Usage of this module typically follows this pattern:

function btsend(files)   // have the user choose a device   dev=bt.select();   if dev#null then     adr=dev['adr'];     // connect after getting the channel for the     // OBEX Push Service     obex.conn(adr, bt.chan(adr, obex.uuid)[0]);     // send all the files     for f in files do       obex.put(f)     end;     obex.close()   end end // send three files btsend(['sample.dat', 'moon.gif', 'bells.mp3'])

• obex.close
• obex.conn
• obex.get
• obex.path
• obex.put
• obex.timeout
• obex.who
• Constants

obex.close

• function close() → null
  Permissions: FreeComm

Closes the connection to the server. Does nothing if there is no connection.

obex.conn

• function conn(adr, channel, password=null) → String
  Permissions: FreeComm

Connects to the OBEX server on the host with Bluetooth address adr, on channel channel. If password#null, it will be used during OBEX authentication.

The channel is normally obtained by querying the hosts service discovery database via bt.chan for obex.uuid.

If successful, returns the "who" name of the OBEX server.

dev="00:0E:07:C9:EE:88"; channel=bt.chan(dev, obex.uuid)[0]; print obex.conn(dev, channel) → peer2

obex.get

• function get(path, name=null) → String
  Permissions: Write(path)+FreeComm

Gets (pulls) a file from the server, storing it in path. The object (or file) to be pulled is given by name. If name=null, it equals to path without any directory components.

Note that not all servers support file pulling.

Throws ErrDisconnected if the client is not connected.

// get a vCard into the cards directory obex.get('\\cards\\William.vcf', 'OwnCard.vcf')

obex.path

• function path(name, create=false) → null
  Permissions: FreeComm

Changes the directory on the server to name. If name="..", changes to the parent directory. If create=true, the directory is also created if it doesn't exist.

Note that not all servers support directories.

Throws ErrDisconnected if the client is not connected.

// change to directory 'images', creating it if required path('images', true); // change back to the parent path('..')

obex.put

• function put(path, name=null, type=null, description=null) → null
  Permissions: Read(path)+FreeComm

Puts (pushes) a file to the server, getting the data from file. The name of the file on the server is given by name, its MIME type by type. description is an optional description of the data for the server.

If name=null, it equals to file without any directory components.

If type=null, it is derived from the file extension for many important file types.

Throws ErrDisconnected if the client is not connected.

// send a screen shot to the server obex.put("c:\\Nokia\\Images\\Fe_img\\Fescr(0).jpg",          "myapp.jpg", "image/jpeg",          "Screen shot of my app")

obex.timeout

• function timeout() → Number
  Permissions: FreeComm
• function timeout(ms) → Number
  Permissions: FreeComm

Gets or sets the timeout used during most functions of this module. Without arguments, returns the current timeout in milliseconds. With one argument, returns the old timeout, and sets the new timeout to ms. Setting the timeout to zero (the default) or a negative value disables timeouts, i.e. OBEX operations can block indefinitely, or use a timeout defined by the underlying system.

The timeout is used in all following calls: whenever an operation does not complete within the given number of milliseconds, it throws ErrTimedOut.

Throws ExcValueOutOfRange if ms exceeds 2147483 (35 minutes and 47.483 seconds).

A timed out call will always close the OBEX connection; obex.conn must be called to reconnect.

obex.who

• function who() → String|null
  Permissions: FreeComm
• function who(name) → String|null
  Permissions: FreeComm

Gets or sets the local "who" name for the next connection.

Without arguments, returns the current "who" name, or null if none is set. With one argument, returns the old name and sets the new name to name. Setting it to null disables sending the "who" name.

Some servers assume a special role if a certain name is presented. For most purposes, you do not need to set a "who" name.

obex.who must be called before obex.conn.

// set the "who" name to 'peer1' obex.who('peer1')

obex Constants

• const uuid = 4357 The standard BT UUID for the Obex Push Service.

---

Next: Module sms: Short Messages

Navigation