servicehints.java

JRed is a 100％ Java implementation of the IrDA infrared communications protocols. JRed lets you beam

/*
**************************************************************************
** $Header: /cvsroot/jred/jred/src/com/synchrona/jred/irlap/ServiceHints.java,v 1.1.1.1 2000/07/05 04:41:53 mpatters Exp $
**
** Copyright (C) 2000 Synchrona, Inc. All rights reserved.
**
** This file is part of JRed, a 100% Java implementation of the IrDA
** infrared communications protocols.
**
** This file may be distributed under the terms of the Synchrona Public
** License as defined by Synchrona, Inc. and appearing in the file
** LICENSE included in the packaging of this file. The Synchrona Public
** License is based on the Q Public License as defined by Troll Tech AS
** of Norway; it differs only in its use of the courts of Florida, USA
** rather than those of Oslo, Norway.
**************************************************************************
*/
package com.synchrona.jred.irlap;

import com.synchrona.util.Assert;

/**
 * IrLMP peers exchange service hints during the connection process
 * to describe their capabilities and to provide a human-readable
 * nickname for discovery logs.
 */
public class ServiceHints {
	/**
	 * Declares support for IR plug-and-play (IrPnP).
	 */
	public static final int PNP = 0x00000001;

	/**
	 * Declares that this device is a PDA.
	 */
	public static final int PDA = 0x00000002;

	/**
	 * Declares that this device is a computer.
	 */
	public static final int COMPUTER = 0x00000004;

	/**
	 * Declares that this device supports IrLPT, the infrared
	 * printing protocol.
	 */
	public static final int PRINTER = 0x00000008;

	/**
	 * Declares that this device is a modem.
	 */
	public static final int MODEM = 0x00000010;

	/**
	 * Declares that this device is a facsimile machine.
	 */
	public static final int FAX = 0x00000020;

	/**
	 * Declares that this device is a TCP/IP LAN access point that
	 * supports IrLAN.
	 */
	public static final int LAN_ACCESS = 0x00000040;

	/**
	 * Signifies the presence of additional bytes of capability information.
	 * Users of ServiceHints need not set this bit, as the constructor
	 * sets it if it is necessary..
	 */
	public static final int BYTE_1_EXTENSION = 0x00000080;

	/**
	 * Declares that this device supports IR telephony.
	 */
	public static final int TELEPHONY = 0x00000100;

	/**
	 * Declares that this device is a file server supporting IrOBEX.
	 */
	public static final int FILE_SERVER = 0x00000200;

	/**
	 * Declares that additional capability bytes follow the second byte.
	 */
	public static final int BYTE_2_EXTENSION = 0x00008000;

	/**
	 * Used in construction to assert that only capabilities supported
	 * by the IrDA standard are declared by a service user. If you're
	 * prototyping something and you just want to create a bogus capability
	 * mask, do <code>(ServiceHints.VALID_BITS)</code>.
	 */
	public static final int VALID_BITS = PNP | PDA | COMPUTER | PRINTER | MODEM | FAX | LAN_ACCESS | BYTE_1_EXTENSION | TELEPHONY | FILE_SERVER | BYTE_2_EXTENSION;

	/**
	 * Indicates that the information string (the nickname) passed into
	 * the constructor is a Unicode string. Note that Java uses UTF-8,
	 * in which ASCII characters are encoded as single bytes; IrDA encodes
	 * all characters (including the terminating null) as
	 * 2-byte entities. Although this has no impact on ServiceHints, it
	 * does mean that the byte sequences representing a ServiceHints
	 * instance may report lengths that seem incorrect to you, especially
	 * if you are printing string lengths in an attempt to debug something.
	 */
	public static final int CHARSET_UNICODE = 255;
	
	/**
	 * IrLMP allows up to 255 characters in a device hints string, but it
	 * also uses a full 16 bits for every Unicode character. That means you
	 * get at most 127 Unicode characters of device information. If you
	 * try to create a ServiceHints instance with more than MAX_STRING_LENGTH
	 * characters, the constructor warns you via nonfatal assertion and
	 * truncates the information.
	 */
	public static final int MAX_STRING_LENGTH = 127;
	
	private int        m_nCapabilityMask;
	private UserString m_nickname;

	public ServiceHints(int nCapabilityMask, String strInfo) {
		// Need a non-empty set of capabilities or there's no point.
		Assert.warn(0 != nCapabilityMask, "No capabilities were specified.");
		// Need to have valid bits to comply with IrDA spec
		Assert.warn((0 == (nCapabilityMask & ~VALID_BITS)), "Invalid bits in capability mask: " + Integer.toBinaryString(nCapabilityMask) + ".");
		// It's allowable but stupid to have null or empty device info.
		Assert.warn((null != strInfo), "Device hints are null.");
		Assert.warn((strInfo.length() > 0), "Device hints is non-null but empty");

		// Make sure they didn't specify an extension byte on byte 1 without
		// any data in byte 2. If they did, assume it was a typo and mask off
		// the offending bit.
		if ( (0 != (nCapabilityMask & BYTE_1_EXTENSION)) && (0 == (nCapabilityMask & 0x0000FF00)) ) {
			Assert.warn(false, "Extension bit was set on capability mask byte 1 but no bits were set in bit 2, correcting.");
			nCapabilityMask &= 0x0000007F;
		}

		// If the user didn't specify extension data, but there is data
		// in byte 2, silently add the extension bit. Users shouldn't have
		// to care about it.
		if ( (0 == (nCapabilityMask & BYTE_1_EXTENSION)) && (0 != (nCapabilityMask & 0x0000FF00)) ) {
			nCapabilityMask &= BYTE_1_EXTENSION;
		}

		// IrLAP device information strings are limited to 255 bytes. Our
		// limit is half that, since we encode device information as 16-bit
		// Unicode characters. If the user has exceeded that limit we need
		// to create a truncated copy of the original.
		if ( strInfo.length() > MAX_STRING_LENGTH ) {
			Assert.warn(false, "Device hints exceeded maximum of " + MAX_STRING_LENGTH + " characters, truncating it.");
			strInfo = strInfo.substring(0, MAX_STRING_LENGTH);
		}

		// Mask off any invalid bits; we've already warned about it above
		m_nCapabilityMask = VALID_BITS & nCapabilityMask;
		m_nickname        = new UserString(strInfo);
	}

	/**
	 * Parse service hints out of bytes in an IrLAPFrame.
	 */
	public ServiceHints(byte [] bytes, int offset, int length) {
		m_nCapabilityMask = 0x0000FFFF & ((bytes[offset] << 8) | (bytes[offset + 1]));
		try {
			m_nickname = new UserString(bytes[offset + 2], // encoding
			                            bytes,
			                            offset + 3,        // skip mask & encoding
			                            length - offset - 3);
		} catch (Exception e) {
			System.err.println("Caught exception: " + e);
			e.printStackTrace(System.err);
			m_nickname = null;
		}
	}

	public int getCapabilities() {
		return m_nCapabilityMask;
	}

	/**
	 * getCharset() always returns the IrLMP identifier for Unicode
	 * character sets.
	 */
	public int getCharset() {
		return CHARSET_UNICODE;
	}

	public UserString getInfo() {
		return m_nickname;
	}

	public byte [] toBytes() {
		byte [] ayBytes = null;

		return ayBytes;
	}

	public String toString() {
		return "ServiceHints [" + Integer.toHexString(m_nCapabilityMask) + " " + m_nickname + "]";
	}
}