ExchangeListener.java

/*
 * Copyright © 2013 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;

import java.util.Vector;

/**
 * 
 * ExchangeListner is an callback interface. By means of the interface
 * function OBEX communication module signal to a listener about
 * various networking events.
 * 
 * This interface is implemented by the BCExchangerMIDlet and OBEX
 * communication classes located in the package bcexchanger.comm use
 * it for signaling
 * 
 */
public interface ExchangeListener {
    
    public static final int ERROR_BUETOOTH_OFF = 1;
    public static final int ERROR_SERVER_IOEXCEPTION = 2;
    

    /**
     * Called when the OBEX communication module completes the inquiry
     * 
     * @param code -
     *          inquiry completion code
     */
    public void onInquiryComplete(int code);

    /**
     * Called when the OBEX communication module completes service
     * discoveries
     * <p>
     * This method is called when service discovery on all devices is
     * complete
     * 
     * @param
     * @param code -
     *          service discovery completion code
     */
    public void onServiceDiscoveryComplete(int code);

    /**
     * This method is called when OBEX communication module needs to
     * resolve services
     * <p>
     * If several services are found, the OBEX communication module asks
     * the MIDlet to resolve the services and choose the only one to
     * connect to
     * 
     * @param friendlyNames -
     *          list of friendly names of devices which has the service
     * @return index of the chosen device/service from the vector
     * @throws InterruptedException
     */
    public int resolveMultipleServices(Vector friendlyNames) throws InterruptedException;

    /**
     * This method returns own business card serialized to vCard/2.1
     * format
     * <p>
     * When OBEX module needs to send the own business card to a remote
     * device it uses this method to request own business card from the
     * MIDlet
     * 
     * @return byte array containing own business card serialized to
     *         vCard/2.1 format null if there were errors or cancellation
     * @throws Exception
     */
    public byte[] getOwnBC() throws Exception;

    /**
     * Called when business card send (Client OBEX PUT) is finished
     * 
     * @param code -
     *          completion code
     */
    public void onSendComplete(int code);

    /**
     * Called when business card receive (Client OBEX GET) is finished
     * 
     * @param code -
     *          completion code
     */
    public void onReceiveComplete(int code);

    /**
     * Called when Server OBEX GET operation is finished
     * 
     * @param code -
     *          completion code
     */
    public void onGetComplete(int code);

    /**
     * Called when Server OBEX PUT operation is finished
     * 
     * @param code -
     *          completion code
     */
    public void onPutComplete(int code);

    /**
     * Called when a business card from a remote device is received
     * <p>
     * This method allows MIDlet to save received business card.
     * 
     * @param vCard -
     *          byte array containing receive business card serialized
     *          to vCard/2.1 format
     * @throws Exception -
     *           if saving of the business card fails
     */
    public void onReceiveBC(byte[] vCard) throws Exception;

    /**
     * Called in case of problems with Bluetooth OBEX server accepting connection
     * 
     */
    public void onServerError(int errorType);
    
    /**
     * Called in case of problems with java.lang.SecurityException
     * 
     */    
    public void onSecurityError();
}