fnet_error.h

00001 /**************************************************************************
00002 *
00003 * Copyright 2011-2016 by Andrey Butok. FNET Community.
00004 * Copyright 2008-2010 by Andrey Butok. Freescale Semiconductor, Inc.
00005 *
00006 ***************************************************************************
00007 *
00008 *  Licensed under the Apache License, Version 2.0 (the "License"); you may
00009 *  not use this file except in compliance with the License.
00010 *  You may obtain a copy of the License at
00011 *
00012 *  http://www.apache.org/licenses/LICENSE-2.0
00013 *
00014 *  Unless required by applicable law or agreed to in writing, software
00015 *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00016 *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00017 *  See the License for the specific language governing permissions and
00018 *  limitations under the License.
00019 *
00020 **********************************************************************/
00021 /*!
00022 *
00023 * @brief Socket error API definitions.
00024 *
00025 ***************************************************************************/
00026 #ifndef _FNET_ERROR_H_
00027 
00028 #define _FNET_ERROR_H_
00029 
00030 /*! @addtogroup fnet_error
00031 * When a socket call indicates a failure, it is possible to call the @ref
00032 * fnet_error_get() function to determine the error value.@n
00033 * Another way to determine the error value for a socket is to examine its
00034 * @ref SO_ERROR option.@n
00035 * Possible values for socket errors are defined by the @ref fnet_error_t.
00036 */
00037 /*! @{ */
00038 
00039 /**************************************************************************/ /*!
00040  * @brief Possible socket error codes, returned by the @ref fnet_error_get(),
00041  * or used by the @ref SO_ERROR option.
00042  ******************************************************************************/
00043 typedef enum
00044 {
00045     FNET_ERR_OK             = (0),  /**< @brief There is no error.
00046                                      */
00047     FNET_ERR_NO_DESC        = (-2),  /**< @brief No more socket descriptors are available.@n
00048                                      *   An application has opened too many sockets.
00049                                      *   The maximum number of available socket descriptors
00050                                      *   is defined by the @ref FNET_CFG_SOCKET_MAX.
00051                                      */
00052     FNET_ERR_NOMEM          = (-3),  /**< @brief Cannot allocate the memory.@n
00053                                      *   The error is indicating a lack of required
00054                                      *   memory resources.
00055                                      */
00056     FNET_ERR_AGAIN          = (-4),  /**< @brief Try again, a retry at some time later may be successful.@n
00057                                      *   This error is returned from operations on sockets
00058                                      *   that cannot be completed immediately. It is a non-fatal error
00059                                      *   and the operation should be retried later.@n
00060                                      *   For example, it is normal for the @ref FNET_ERR_AGAIN to be reported as
00061                                      *   the result from the @ref fnet_socket_connect() calling on a @ref SOCK_STREAM socket,
00062                                      *   since some time must elapse for the connection to be established.
00063                                      */
00064     FNET_ERR_BOUNDREQ       = (-5),  /**< @brief The socket has not been bound with @ref fnet_socket_bind().@n
00065                                      *   A socket must be bound to an address before calling
00066                                      *   @ref fnet_socket_getname(), @ref fnet_socket_recvfrom(), @ref fnet_socket_recv(), and @ref fnet_socket_listen().
00067                                      */
00068     FNET_ERR_INVAL          = (-6),  /**< @brief Invalid argument.@n
00069                                      *   An invalid argument was supplied.
00070                                      */
00071     FNET_ERR_DESTADDRREQ    = (-7),  /**< @brief Destination address required.@n
00072                                      *   A required address was omitted from an operation on a socket.
00073                                      *   For example, this error will be returned, if the @ref fnet_socket_sendto()
00074                                      *   or @ref fnet_socket_connect() is called with the remote address of @ref INADDR_ANY.
00075                                      */
00076     FNET_ERR_MSGSIZE        = (-8),  /**< @brief Message too long.@n
00077                                      *   A message sent on a datagram socket was larger than the internal
00078                                      *   message buffer, or some other network limit, or the buffer,
00079                                      *   which is used to receive a datagram was smaller than the datagram itself.
00080                                      */
00081     FNET_ERR_NOPROTOOPT     = (-9),  /**< @brief Bad protocol option. @n
00082                                      *   An unknown, invalid, or unsupported option or level was specified
00083                                      *   in the @ref fnet_socket_getopt(), or @ref fnet_socket_setopt() call, or a socket
00084                                      *   received Parameter Problem ICMP Error Message.
00085                                      */
00086     FNET_ERR_PROTONOSUPPORT = (-10), /**< @brief Protocol not supported.@n
00087                                      *   This error occurs if an application attempts to call @ref fnet_socket()
00088                                      *   and the requested protocol has not been configured into the system,
00089                                      *   or no implementation for it exists.
00090                                      */
00091     FNET_ERR_OPNOTSUPP      = (-11), /**< @brief Operation not supported.@n
00092                                      *   The attempted operation is not supported for the type
00093                                      *   of socket referenced. This occurs, when socket cannot support
00094                                      *   the requested operation, for example trying to accept
00095                                      *   a connection on a datagram socket.
00096                                      */
00097     FNET_ERR_AFNOSUPPORT    = (-12), /**< @brief Address family not supported by the protocol family.@n
00098                                      *   The stack supports only the @ref AF_INET family.
00099                                      *   This error will be returned, if an address of a wrong family
00100                                      *   is used for a socket in @ref fnet_socket(), @ref fnet_socket_sendto(), @ref fnet_socket_connect(),
00101                                      *   @ref fnet_socket_bind(), @ref fnet_socket_getname(), and in @ref fnet_socket_getpeername().
00102                                      */
00103     FNET_ERR_ADDRINUSE      = (-14), /**< @brief Address already in use.@n
00104                                      *   This error occurs, if an application attempts to @ref fnet_socket_bind() or
00105                                      *   @ref fnet_socket_connect() a socket to an IP address and port that has
00106                                      *   already been used for an existing socket, or a socket that
00107                                      *   wasn't closed properly, or one that is still in the process of closing.
00108                                      *   Only one usage of each socket address is permitted.
00109                                      */
00110     FNET_ERR_ADDRNOTAVAIL   = (-15), /**< @brief Cannot assign the requested address.@n
00111                                      *   The requested address is not valid in its context.
00112                                      *   It normally results from an attempt to @ref fnet_socket_bind() to an address
00113                                      *   that is not valid for the local machine. This may also result
00114                                      *   from @ref fnet_socket_connect(), when the remote address or port is not
00115                                      *   valid for a remote machine (for example address or port is 0).
00116                                      */
00117     FNET_ERR_NETUNREACH     = (-16), /**< @brief The network is unreachable.@n
00118                                      *   This error occurs, if socket cannot function at this time,
00119                                      *   because the underlying network interface it uses to provide
00120                                      *   the network services is unavailable.
00121                                      */
00122     FNET_ERR_CONNABORTED    = (-17), /**< @brief Software caused the connection abort.@n
00123                                      *   An established connection was aborted due to a data
00124                                      *   transmission or connection timeouts.
00125                                      */
00126     FNET_ERR_CONNRESET      = (-18), /**< @brief Connection reset by peer. @n
00127                                      *   A connection was forcibly closed by the remote host.
00128                                      *   This normally results, if the peer application on the remote
00129                                      *   host has suddenly stopped, the host has rebooted, or the
00130                                      *   remote host used a "hard close" on the remote socket.@n
00131                                      *   For the UDP sockets, the remote host was unable to deliver
00132                                      *   a previously sent UDP datagram and responded with
00133                                      *   a "Port Unreachable" ICMP packet. The application
00134                                      *   should close the socket as it is no longer usable.
00135                                      */
00136     FNET_ERR_ISCONN         = (-19), /**< @brief Socket is already connected.@n
00137                                      *   A @ref fnet_socket_connect() or @ref fnet_socket_listen() request was made on
00138                                      *   an already connected socket.
00139                                      */
00140     FNET_ERR_NOTCONN        = (-20), /**< @brief Socket is not connected.@n
00141                                      *   A request to send or receive data was not allowed
00142                                      *   because the socket is not connected.
00143                                      */
00144     FNET_ERR_SHUTDOWN       = (-21), /**< @brief The socket has been shut down.@n
00145                                      *   A request to send or receive data was not allowed because
00146                                      *   the socket had already been shut down in that direction
00147                                      *   with a previous @ref fnet_socket_shutdown() call.
00148                                      */
00149     FNET_ERR_INPROGRESS     = (-22), /**< @brief The action is in progress.@n
00150                                      *   An operation was attempted on a
00151                                      *   socket that already had an operation in
00152                                      *   progress - in other words calling @ref fnet_socket_connect() a second time on a
00153                                      *   socket that is already connecting.
00154                                      */
00155     FNET_ERR_TIMEDOUT       = (-23), /**< @brief The connection has timed out.@n
00156                                      *   A connection attempt failed because the connected party did
00157                                      *   not properly respond after a period of time.
00158                                      */
00159     FNET_ERR_HOSTUNREACH    = (-24), /**< @brief No route to a host.@n
00160                                      *   A socket operation was attempted to an unreachable host.
00161                                      */
00162     FNET_ERR_SYSNOTREADY    = (-25), /**< @brief Network subsystem is unavailable.@n
00163                                      *   The stack is not initialized.
00164                                      */
00165     FNET_ERR_CONNCLOSED     = (-26), /**< @brief Connection closed by peer. @n
00166                                      * The final (FIN) segment arrived and there is no data
00167                                      * in the socket receive buffer.
00168                                      * The remote host closed connection and will
00169                                      * not send any data in the current connection. @n
00170                                      * The application should close the socket as it
00171                                      * is no longer usable.
00172                                      */
00173     FNET_ERR_IPDISABLED    = (-27),   /**< @brief IP operation is disabled. @n
00174                                      * It happens when Duplicate Address Detection
00175                                      * fails for interface link-local address,
00176                                      * formed from an interface identifier based on the hardware address.
00177                                      */
00178     FNET_ERR_BAD_DESC       = (-28)  /**< @brief Bad socket descriptor.@n
00179                                      *   An operation was attempted on a socket descriptor
00180                                      *   that does not refer to a valid socket.
00181                                      */
00182 } fnet_error_t;
00183 
00184 #if defined(__cplusplus)
00185 extern "C" {
00186 #endif
00187 
00188 /***************************************************************************/ /*!
00189  *
00190  * @brief Returns the last error that occurred.
00191  *
00192  * @return This function returns the error code for the last socket
00193  *         operation that failed.@n
00194  *         The error codes are defined by the @ref fnet_error_t.
00195  *
00196  * @see fnet_error_set()
00197  *
00198  ******************************************************************************
00199  *
00200  *   When a particular socket function indicates that an error has occurred,
00201  *   this function should be called to retrieve the appropriate error code.@n
00202  *   A successful socket function call, or a call to @ref fnet_error_get(),
00203  *   does not reset the error code. To reset the error code, use the fnet_error_set()
00204  *   function call with error set to zero (@ref FNET_ERR_OK).
00205  *
00206  ******************************************************************************/
00207 fnet_error_t fnet_error_get( void );
00208 
00209 /***************************************************************************/ /*!
00210  *
00211  * @brief Sets the error code.
00212  *
00213  * @param error  Error code.
00214  *
00215  * @see fnet_error_get()
00216  *
00217  ******************************************************************************
00218  *
00219  *   This function is used to set or reset the error code. @n
00220  *   Note that any subsequent socket routine called by the application will
00221  *   override the error code, as set by this routine.
00222  *
00223  ******************************************************************************/
00224 void fnet_error_set( fnet_error_t error );
00225 
00226 #if defined(__cplusplus)
00227 }
00228 #endif
00229 
00230 /*! @} */
00231 
00232 #endif