ExchangerComm.java

/*
 * Copyright © 2012 Nokia Corporation. All rights reserved.
 * Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation. 
 * Oracle and Java are trademarks or registered trademarks of Oracle and/or its
 * affiliates. Other product and company names mentioned herein may be trademarks
 * or trade names of their respective owners. 
 * See LICENSE.TXT for license information.
 */ 
package com.nokia.example.bcexchanger.comm;

/**
 * 
 * This is an interface to OBEX communication module. OBEX
 * communication module implemented by the classes from
 * bcexchanger.comm package realize exchange of the business card over
 * JSR82 OBEX. The controls of the module is abstracted in this
 * interface.
 * 
 * BCExchanger is calling the methods of this interface implemented by
 * ExchangerCommImpl class to control OBEX communication.
 * 
 * 
 */
public interface ExchangerComm {

    // Constant field declaration
    static final int DONE = 0;
    static final int CANCELED = 1;
    static final int ERROR = 2;
    static final int NO_RECORDS = 3;

    /**
     * Initiate whole procedure of sending business card to a remote
     * device
     * <p>
     * The method start the procedure of inquiry, service discovery,
     * transferring own card and receiving the card from the remote
     * device. This method is asynchronous and it returns immediately
     * after operation is started.
     * 
     * @exception Exception -
     *              if any immediate errors occur while the process is
     *              started. In practice it is thrown when inquiry
     *              cannot start or if this method is called while
     *              sending process is in progress
     */
    public void startSending() throws Exception;

    /**
     * Cancels the process of sending
     * <p>
     * The method cancels the current operation of the sending: inquiry,
     * service discovery, OBEX send or receive and returns to the idle
     * state.
     * 
     */
    public void cancelSending();

    /**
     * Starts to listen for incoming connections
     * <p>
     * The method start listening for incoming connections. This method
     * is asynchronous and it returns immediately after the connection
     * listening is started.
     * 
     */
    public void startWaiting();

    /**
     * This method stops listening for incoming connection
     * <p>
     * The method stops listening for incoming connection if
     * startWaiting() was called before. Otherwise method does nothing.
     * 
     */
    public void cancelWaiting();
}