1 /*

     2 * Copyright (c) 2004 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:

    15 *

    16 */

    17 

    18 

    19 package com.nokia.mj.impl.gcf.utils;

    20 

    21 import java.io.IOException;

    22 import com.nokia.mj.impl.rt.support.Jvm;

    23 

    24 /**

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

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

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

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

    29  * NativeError.cpp.

    30  */

    31 public final class NativeError

    32 {

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

    34     private static final int BUFFER_SIZE = 256;

    35 

    36     // SymbianOS error codes

    37     public static final int KErrNone = 0;

    38     public static final int KErrNotFound = -1;

    39     public static final int KErrGeneral = -2;

    40     public static final int KErrCancel = -3;

    41     public static final int KErrNoMemory = -4;

    42     public static final int KErrNotSupported = -5;

    43     public static final int KErrArgument = -6;

    44     public static final int KErrOverflow = -9;

    45     public static final int KErrAlreadyExists = -11;

    46     public static final int KErrPathNotFound = -12;

    47     public static final int KErrDied = -13;

    48     public static final int KErrNotReady = -18;

    49     public static final int KErrCorrupt = -20;

    50     public static final int KErrAccessDenied = -21;

    51     public static final int KErrWrite = -23;

    52     public static final int KErrEof = -25;

    53     public static final int KErrDiskFull = -26;

    54     public static final int KErrBadName = -28;

    55     public static final int KErrCommsLineFail = -29;

    56     public static final int KErrTimedOut = -33;

    57     public static final int KErrDisconnected = -36;

    58     public static final int KErrTooBig = -40;

    59     public static final int KErrDivideByZero = -41;

    60     public static final int KErrHardwareNotAvailable = -44;

    61 

    62     static

    63     {

    64         try

    65         {

    66             // Load the native libraries

    67             Jvm.loadSystemLibrary("javagcf");

    68         }

    69         catch (Exception e)

    70         {

    71             StreamsLogger.ELog("Unable to load native libraries!");

    72         }

    73     }

    74 

    75     // Not intended to be constructed

    76     private NativeError()

    77     {

    78     }

    79 

    80 

    81 

    82     /**

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

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

    85      * Otherwise just returns the error.

    86      *

    87      * @param aError Possible error code.

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

    89      * @throws OutOfMemoryError If aError equals KErrNoMemory.

    90      * @throws IllegalArgumentException If aError equals KErrArgument

    91      * @throws ArithmeticException If aError equals KErrDivideByZero

    92      */

    93     public static int checkExplicitOnly(int aError)

    94     {

    95         if (aError < KErrNone)

    96         {

    97             switch (aError)

    98             {

    99             case KErrNoMemory:

   100                 throw new OutOfMemoryError();

   101                 // KErrArgument must throw IllegalArgumentException

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

   103             case KErrArgument:

   104                 throw new IllegalArgumentException();

   105             case KErrDivideByZero:

   106                 throw new ArithmeticException();

   107             default:

   108                 // Do nothing

   109             }

   110         }

   111         return aError;

   112     }

   113 

   114 

   115 

   116     /**

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

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

   119      * Otherwise throws basic Error class.

   120      *

   121      * @param aError Possible error code.

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

   123      * if the error code is not recognised.

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

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

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

   127      */

   128     public static int check(int aError)

   129     {

   130         if (aError < KErrNone)

   131         {

   132             checkExplicitOnly(aError);

   133             throw new Error(errorMessage(aError));

   134         }

   135         return aError;

   136     }

   137 

   138 

   139 

   140     /**

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

   142      */

   143     public static long check(long aError)

   144     {

   145         check((int)aError);

   146         return aError;

   147     }

   148 

   149 

   150 

   151     /**

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

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

   154      * Otherwise throws an IOException.

   155      *

   156      * @param aError Possible error code.

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

   158      */

   159     public static int checkIO(int aError)

   160     throws IOException

   161     {

   162         if (aError < KErrNone)

   163         {

   164             checkExplicitOnly(aError);

   165             throw new IOException(errorMessage(aError));

   166         }

   167         return aError;

   168     }

   169 

   170 

   171 

   172     /**

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

   174      * if true. Otherwise throws basic Error class.

   175      *

   176      * @param aError Possible error code.

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

   178      */

   179     public static int checkOOM(int aError)

   180     {

   181         if (aError < KErrNone)

   182         {

   183             if (aError == KErrNoMemory)

   184             {

   185                 throw new OutOfMemoryError();

   186             }

   187             throw new Error(errorMessage(aError));

   188         }

   189         return aError;

   190     }

   191 

   192 

   193 

   194     /**

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

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

   197      * returned from a native method.

   198      *

   199      * @param aObject Object that may be null.

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

   201      */

   202     public static Object checkOOM(Object aObject)

   203     {

   204         if (aObject == null)

   205         {

   206             throw new OutOfMemoryError();

   207         }

   208         return aObject;

   209     }

   210 

   211 

   212 

   213     /**

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

   215      * if true. Does not throw anything otherwise.

   216      *

   217      * @param aError Possible error code.

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

   219      */

   220     public static int checkOOMOnly(int aError)

   221     {

   222         if (aError == KErrNoMemory)

   223         {

   224             throw new OutOfMemoryError();

   225         }

   226         return aError;

   227     }

   228 

   229 

   230 

   231     /**

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

   233      * code comes from and the error code given.

   234      *

   235      * @param A native error code.

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

   237      */

   238     public static String errorMessage(int aError)

   239     {

   240         final String message = _getNativeErrorMessage(aError);

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

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

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

   244         return result;

   245     }

   246 

   247 

   248 

   249     /**

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

   251      * code comes from and the error code given.

   252      *

   253      * @param A native error code.

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

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

   256      */

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

   258     {

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

   260         messageBuf.append(aExtraText);

   261         messageBuf.append(", ");

   262         messageBuf.append(errorMessage(aError));

   263         return messageBuf.toString();

   264     }

   265 

   266 

   267     private static native String _getNativeErrorMessage(int aError);

   268 

   269 }

   270 

   271