1 /*

     2 * Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: Native Error Descriptions for M2G Component.

    15 *

    16 */

    17 

    18 

    19 package com.nokia.microedition.m2g;

    20 

    21 import java.io.IOException;

    22 

    23 /**

    24  * A utility class for declaring and handling native SymbianOS error codes.

    25  * All error codes that are used in Java from native code should be

    26  * declared here and referenced from this class. Also if a new error code

    27  * is added, it should be added to the list of compile-time asserts in

    28  * NativeError.cpp.

    29  */

    30 public final class NativeError

    31 {

    32     public static final String NATIVE_ERROR_MESSAGE = "SymbianOS error = ";

    33     private static final int BUFFER_SIZE = 256;

    34 

    35     // SymbianOS error codes

    36     public static final int KErrNone = 0;

    37     public static final int KErrNotFound = -1;

    38     public static final int KErrGeneral = -2;

    39     public static final int KErrCancel = -3;

    40     public static final int KErrNoMemory = -4;

    41     public static final int KErrNotSupported = -5;

    42     public static final int KErrArgument = -6;

    43     public static final int KErrOverflow = -9;

    44     public static final int KErrAlreadyExists = -11;

    45     public static final int KErrPathNotFound = -12;

    46     public static final int KErrDied = -13;

    47     public static final int KErrNotReady = -18;

    48     public static final int KErrCorrupt = -20;

    49     public static final int KErrAccessDenied = -21;

    50     public static final int KErrWrite = -23;

    51     public static final int KErrEof = -25;

    52     public static final int KErrDiskFull = -26;

    53     public static final int KErrBadName = -28;

    54     public static final int KErrCommsLineFail = -29;

    55     public static final int KErrTimedOut = -33;

    56     public static final int KErrDisconnected = -36;

    57     public static final int KErrTooBig = -40;

    58     public static final int KErrDivideByZero = -41;

    59     public static final int KErrHardwareNotAvailable = -44;

    60 

    61 

    62     // Not intended to be constructed

    63     private NativeError()

    64     {

    65     }

    66 

    67 

    68 

    69     /**

    70      * Checks for basic native error codes that map to standard Java

    71      * exceptions and throws the exception if the error code matches.

    72      * Otherwise just returns the error.

    73      *

    74      * @param aError Possible error code.

    75      * @return Value passed in is returned if not an error.

    76      * @throws OutOfMemoryError If aError equals KErrNoMemory.

    77      * @throws IllegalArgumentException If aError equals KErrArgument

    78      * @throws ArithmeticException If aError equals KErrDivideByZero

    79      */

    80     public static int checkExplicitOnly(int aError)

    81     {

    82         if (aError < KErrNone)

    83         {

    84             switch (aError)

    85             {

    86             case KErrNoMemory:

    87                 throw new OutOfMemoryError();

    88                 // KErrArgument must throw IllegalArgumentException

    89                 // otherwise lcdui will break, so don't change this.

    90             case KErrArgument:

    91                 throw new IllegalArgumentException();

    92             case KErrDivideByZero:

    93                 throw new ArithmeticException();

    94             default:

    95                 // Do nothing

    96             }

    97         }

    98         return aError;

    99     }

   100 

   101 

   102 

   103     /**

   104      * Checks for basic native error codes that map to standard Java

   105      * exceptions and throws the exception if the error code matches.

   106      * Otherwise throws basic Error class.

   107      *

   108      * @param aError Possible error code.

   109      * @param aThrowAlways Determines whether a default exception is thrown

   110      * if the error code is not recognised.

   111      * @return Value passed in is returned if not an error.

   112      * @throws Error If the error code does not match any exception thrown

   113      * in checkExplicitOnly, a default exception is thrown here.

   114      */

   115     public static int check(int aError)

   116     {

   117         if (aError < KErrNone)

   118         {

   119             checkExplicitOnly(aError);

   120             throw new Error(errorMessage(aError));

   121         }

   122         return aError;

   123     }

   124 

   125 

   126 

   127     /**

   128      * Version of check that uses a long rather than an int.

   129      */

   130     public static long check(long aError)

   131     {

   132         check((int)aError);

   133         return aError;

   134     }

   135 

   136 

   137 

   138     /**

   139      * Checks for basic native error codes that map to standard Java

   140      * exceptions and throws the exception if the error code matches.

   141      * Otherwise throws an IOException.

   142      *

   143      * @param aError Possible error code.

   144      * @return Value passed in is returned if not an error.

   145      */

   146     public static int checkIO(int aError)

   147     throws IOException

   148     {

   149         if (aError < KErrNone)

   150         {

   151             checkExplicitOnly(aError);

   152             throw new IOException(errorMessage(aError));

   153         }

   154         return aError;

   155     }

   156 

   157 

   158 

   159     /**

   160      * Checks if the error code represents out of memory, and throws Java Error

   161      * if true. Otherwise throws basic Error class.

   162      *

   163      * @param aError Possible error code.

   164      * @return Value passed in is returned if not an error.

   165      */

   166     public static int checkOOM(int aError)

   167     {

   168         if (aError < KErrNone)

   169         {

   170             if (aError == KErrNoMemory)

   171             {

   172                 throw new OutOfMemoryError();

   173             }

   174             throw new Error(errorMessage(aError));

   175         }

   176         return aError;

   177     }

   178 

   179 

   180 

   181     /**

   182      * Checks if the object is a null reference, and throws OutOfMemoryError

   183      * if this is the case. Useful for checking for OOM when Java objects

   184      * returned from a native method.

   185      *

   186      * @param aObject Object that may be null.

   187      * @return Value passed in is returned if not an error.

   188      */

   189     public static Object checkOOM(Object aObject)

   190     {

   191         if (aObject == null)

   192         {

   193             throw new OutOfMemoryError();

   194         }

   195         return aObject;

   196     }

   197 

   198 

   199 

   200     /**

   201      * Checks if the error code represents out of memory, and throws Java Error

   202      * if true. Does not throw anything otherwise.

   203      *

   204      * @param aError Possible error code.

   205      * @return Value passed in is returned if not an out of memory error.

   206      */

   207     public static int checkOOMOnly(int aError)

   208     {

   209         if (aError == KErrNoMemory)

   210         {

   211             throw new OutOfMemoryError();

   212         }

   213         return aError;

   214     }

   215 

   216 

   217 

   218     /**

   219      * Returns a string formatted with generic text to indicate where the error

   220      * code comes from and the error code given.

   221      *

   222      * @param A native error code.

   223      * @return A string containing the error code and explanatory text.

   224      */

   225     public static String errorMessage(int aError)

   226     {

   227         final String message = _getNativeErrorMessage(aError);

   228         String result = NATIVE_ERROR_MESSAGE.concat(Integer.toString(aError));

   229         if (message != null &&  message.length() > 0)

   230             result = result.concat(" : ").concat(message);

   231         return result;

   232     }

   233 

   234     /**

   235      * Returns a string formatted with generic text to indicate where the error

   236      * code comes from and the error code given.

   237      *

   238      * @param A native error code.

   239      * @param An extra text message for more information.

   240      * @return A string containing the error code and explanatory text.

   241      */

   242     public static String errorMessage(int aError, String aExtraText)

   243     {

   244         final StringBuffer messageBuf = new StringBuffer(BUFFER_SIZE);   // use native max as base

   245         messageBuf.append(aExtraText);

   246         messageBuf.append(", ");

   247         messageBuf.append(errorMessage(aError));

   248         return messageBuf.toString();

   249     }

   250 

   251 

   252     private static native String _getNativeErrorMessage(int aError);

   253 

   254 }

   255 

   256