/*
 * Message.java
 *
 * Copyright (c) 2007  Vreixo Formoso
 *
 * This library is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * See COPYING file for details.
 */

package org.pykix.libburnia.libburn;

/**
 * Message from libburn.
 * 
 * <p>
 * Only fatal messages are printed to stderr by default. This class allows you
 * to change that behavior.
 * 
 * <p>
 * Indeed, you can also select message queuing, which allows you to retrieve
 * the messages. TODO
 * 
 * @author Vreixo Formoso
 * @since 0.1
 */
public class Message {

	/** */
	public enum Severity {
		NEVER, FATAL, SORRY, WARNING, HINT, NOTE, UPDATE, DEBUG, ALL
	}
	
	private int errorCode;
	private String msgText;
	private int osErrno;
	private Severity severity;
	
	/* it's to be called from JNI code */
	Message(int errorCode, String msgText, int osErrno, String severity) {
		super();
		this.errorCode = errorCode;
		this.msgText = msgText;
		this.osErrno = osErrno;
		this.severity = Severity.valueOf(severity);
	}
	
	/**
	 * Get the a unique error code as listed in libburn/libdax_msgs.h
	 * 
	 * TODO i need to get the errcodes and list it here, maybe as a enum,
	 *      maybe as integer constants!!
	 */
	public int getErrorCode() {
		return errorCode;
	}

	/**
	 * Get a text describing the message
	 */
	public String getMsgText() {
		return msgText;
	}

	/**
	 * Get the eventual errno related to the message.
	 */
	public int getOsErrno() {
		return osErrno;
	}

	/**
	 * Severity related to the message.
	 */
	public Severity getSeverity() {
		return severity;
	}

	/**
	 * Control queueing and stderr printing of messages from libburn.
	 * 
	 * @param queueSeverity
	 * 		Gives the minimum limit for messages to be queued.
	 *      Default: {@link Severity#NEVER}. If you queue messages then you
	 *      must consume them by burn_msgs_obtain().
	 * @param printSeverity
	 * 		Does the same for messages to be printed directly
	 * 		to stderr. Default: {@link Severity#FATAL}.
	 * @param printId
	 * 		A text prefix to be printed before the message.
	 * @return
	 * 		<code>true</code> for success, <code>false</code> for error.
	 */
	public static boolean setSeverities(Severity queueSeverity,
			Severity printSeverity, String printId) {
		
		return ( burn_msgs_set_severities(queueSeverity.name(), 
				printSeverity.name(), printId) > 0);
	}
	
	/**
	 * Obtain the oldest pending libburn message from the queue which has at
	 * least the given minSeverity. This message and any older message of
	 * lower severity will get discarded from the queue and is then lost 
	 * forever.
	 * 
	 * @param minSeverity
	 * 		The minimum severity that a message must have to be retrieved.
	 * 		To call with minSeverity {@link Severity#NEVER} will discard the
	 * 		whole queue.
	 * @return
	 * 		The oldest pending message or <code>null</code> if a message
	 * 		with given or higher priority wasn't found.
	 */
	/*
	 * TODO this implementation forgets the error that C function can throw!!
	 */
	public static Message obtain(Severity minSeverity) {
		return burn_msgs_obtain( minSeverity.name() );
	}

	private static native int burn_msgs_set_severities(String queueSeverity,
			String printSeverity, String printId);
	
	private static native Message burn_msgs_obtain(String minSeverity);
}