javax.obex.ClientSession Maven / Gradle / Ivy
/**
* BlueCove - Java library for Bluetooth
*
* Java docs licensed under the Apache License, Version 2.0
* http://www.apache.org/licenses/LICENSE-2.0
* (c) Copyright 2001, 2002 Motorola, Inc. ALL RIGHTS RESERVED.
*
* @version $Id: ClientSession.java 549 2007-06-22 22:19:46Z skarzhevskyy $
*/
package javax.obex;
import java.io.IOException;
import javax.microedition.io.Connection;
/**
* The ClientSession interface provides methods for OBEX
* requests. This interface provides a way to define headers for any OBEX
* operation. OBEX operations are CONNECT, SETPATH, PUT, GET and DISCONNECT. For
* PUTs and GETs, this interface will return a javax.obex.Operation
* object to complete the operations. For CONNECT, DISCONNECT, and SETPATH
* operations, this interface will complete the operation and return the result
* in a HeaderSet object.
*
* Connection ID and Target Headers
*
* According to the IrOBEX specification, a packet may not contain a Connection
* ID and Target header. Since the Connection ID header is managed by the
* implementation, it will not send a Connection ID header if a Connection ID
* was specified in a packet that has a Target header. In other words, if an
* application adds a Target header to a HeaderSet object used in
* an OBEX operation and a Connection ID was specified, no Connection ID will be
* sent in the packet containing the Target header.
*
* CREATE-EMPTY and PUT-DELETE Requests
*
* To perform a CREATE-EMPTY request, the client must call the
* put() method. With the Operation object
* returned, the client must open the output stream by calling
* openOutputStream() and then close the stream by calling
* close() on the OutputStream without writing any
* data. Using the DataOutputStream returned from
* openDataOutputStream() works the same way.
*
* There are two ways to perform a PUT-DELETE request. The delete()
* method is one way to perform a PUT-DELETE request. The second way to perform
* a PUT-DELETE request is by calling put() and never calling
* openOutputStream() or openDataOutputStream() on
* the Operation object returned from put().
*
* PUT example
*
*
*
* void putObjectViaOBEX(ClientSession conn, HeaderSet head, byte[] obj) throws IOException {
*
* // Include the length header
* head.setHeader(HeaderSet.LENGTH, new Long(obj.length));
*
* // Initiate the PUT request
* Operation op = conn.put(head);
*
* // Open the output stream to put the object to it
* OutputStream out = op.openOutputStream();
*
* // Send the object to the server
* out.write(obj);
*
* // End the transaction
* out.close();
* op.close();
* }
*
*
*
* GET example
*
*
*
* byte[] getObjectViaOBEX(ClientSession conn, HeaderSet head) throws IOException {
*
* // Send the initial GET request to the server
* Operation op = conn.get(head);
*
* // Get the object from the input stream
* InputStream in = op.openInputStream();
*
* ByteArrayOutputStream out = new ByteArrayOutputStream();
* int data = in.read();
* while (data != -1) {
* out.write((byte) data);
* data = in.read();
* }
*
* // End the transaction
* in.close();
* op.close();
*
* byte[] obj = out.toByteArray();
* out.close();
*
* return obj;
* }
*
*
* @version 1.0 February 11, 2002
*/
public interface ClientSession extends Connection {
/**
* Sets the Authenticator to use with this connection. The
* Authenticator allows an application to respond to
* authentication challenge and authentication response headers. If no
* Authenticator is set, the response to an authentication
* challenge or authentication response header is implementation dependent.
*
* @param auth
* the Authenticator to use for this connection
*
* @exception NullPointerException
* if auth is null
*/
public void setAuthenticator(Authenticator auth);
/**
* Creates a javax.obex.HeaderSet object. This object can be
* used to define header values in a request.
*
* @see HeaderSet
*
* @return a new javax.obex.HeaderSet object
*/
public HeaderSet createHeaderSet();
/**
* Sets the connection ID header to include in the request packets. If a
* connection ID is set, it will be sent in each request to the server
* except for the CONNECT request. An application only needs to set the
* connection ID if it is trying to operate with different targets over the
* same transport layer connection. If a client receives a connection ID
* from the server, the implementation will continue to use that connection
* ID until the application changes it or until the connection is closed.
*
* @param id
* the connection ID to use
*
* @exception IllegalArgumentException
* if id is not in the range 0 to 232-1
*/
public void setConnectionID(long id);
/**
* Retrieves the connection ID that is being used in the present connection.
* This method will return -1 if no connection ID is being used.
*
* @return the connection ID being used or -1 if no connection ID is being
* used
*/
public long getConnectionID();
/**
* Completes an OBEX CONNECT operation. If the headers
* argument is null, no headers will be sent in the request.
* This method will never return null.
*
* This method must be called and a successful response code of
* OBEX_HTTP_OK must be received before put(),
* get(), setPath(), delete(),
* or disconnect() may be called. Similarly, after a
* successful call to disconnect(), this method must be
* called before calling put(), get(),
* setPath(), delete(), or
* disconnect().
*
* @param headers
* the headers to send in the CONNECT request
*
* @return the headers that were returned from the server
*
* @exception IOException
* if an error occurred in the transport layer; if the client
* is already in an operation; if this method had already
* been called with a successful response code of
* OBEX_HTTP_OK and calls to
* disconnect() have not returned a response
* code of OBEX_HTTP_OK; if the headers
* defined in headers exceed the max packet
* length
*
* @exception IllegalArgumentException
* if headers was not created by a call to
* createHeaderSet()
*/
public HeaderSet connect(HeaderSet headers) throws IOException;
/**
* Completes an OBEX DISCONNECT operation. If the headers
* argument is null, no headers will be sent in the request.
* This method will end the session. A new session may be started by calling
* connect(). This method will never return
* null.
*
* @param headers
* the header to send in the DISCONNECT request
*
* @return the headers returned by the server
*
* @exception IOException
* if an error occurred in the transport layer; if the client
* is already in an operation; if an OBEX connection does not
* exist because connect() has not been
* called; if disconnect() has been called and
* received a response code of OBEX_HTTP_OK
* after the last call to connect(); if the
* headers defined in headers exceed the max
* packet length
*
* @exception IllegalArgumentException
* if headers were not created by a call to
* createHeaderSet()
*/
public HeaderSet disconnect(HeaderSet headers) throws IOException;
/**
* Completes an OBEX SETPATH operation. This method will never return
* null.
*
* @param backup
* if true, instructs the server to back up one
* directory before moving to the directory specified in name
* (similar to cd .. on PCs); if false, apply
* name to the current directory
*
* @param create
* if true, instructs the server to create the
* directory if it does not exist; if false,
* instruct the server to return an error code if the directory
* does not exist
*
* @param headers
* the headers to include in the SETPATH request
*
* @return the headers that were returned from the server
*
* @exception IOException
* if an error occurred in the transport layer; if the client
* is already in an operation; if an OBEX connection does not
* exist because connect() has not been
* called; if disconnect() had been called and
* a response code of OBEX_HTTP_OK was
* received; if the headers defined in headers
* exceed the max packet length
*
* @exception IllegalArgumentException
* if headers were not created by a call to
* createHeaderSet()
*/
public HeaderSet setPath(HeaderSet headers, boolean backup, boolean create) throws IOException;
/**
* Performs an OBEX DELETE operation. This method will never return
* null.
*
* @param headers
* the header to send in the DELETE request
*
* @return the headers returned by the server
*
* @exception IOException
* if an error occurred in the transport layer; if the client
* is already in an operation; if an OBEX connection does not
* exist because connect() has not been
* called; if disconnect() had been called and
* a response code of OBEX_HTTP_OK was
* received; if the headers defined in headers
* exceed the max packet length
*
* @exception IllegalArgumentException
* if headers were not created by a call to
* createHeaderSet()
*/
public HeaderSet delete(HeaderSet headers) throws IOException;
/**
* Performs an OBEX GET operation. This method will send the OBEX headers
* provided to the server and return an Operation object to
* continue with the operation. This method will never return
* null.
*
* @see Operation
*
* @param headers
* the OBEX headers to send as part of the initial GET request
*
* @return the OBEX operation that will complete the GET request
*
* @exception IOException
* if an error occurred in the transport layer; if an OBEX
* connection does not exist because connect()
* has not been called; if disconnect() had
* been called and a response code of
* OBEX_HTTP_OK was received; if
* connect() has not been called; if the
* client is already in an operation;
*
* @exception IllegalArgumentException
* if headers were not created by a call to
* createHeaderSet()
*/
public Operation get(HeaderSet headers) throws IOException;
/**
* Performs an OBEX PUT operation. This method will send the OBEX headers
* provided to the server and return an Operation object to
* continue with the PUT operation. This method will never return
* null.
*
* @see Operation
*
* @param headers
* the OBEX headers to send in the initial PUT request
*
* @return the operation object used to complete the PUT request
*
* @exception IOException
* if an error occurred in the transport layer; if an OBEX
* connection does not exist because connect()
* has not been called; if disconnect() had
* been called and a response code of
* OBEX_HTTP_OK was received; if
* connect() has not been called; if the
* client is already in an operation;
*
* @exception IllegalArgumentException
* if headers were not created by a call to
* createHeaderSet()
*/
public Operation put(HeaderSet headers) throws IOException;
}