SocketConnectable.hs


{- |
Copyright  : Will Thompson, Iñaki García Etxebarria and Jonas Platte
License    : LGPL-2.1
Maintainer : Iñaki García Etxebarria (inaki@blueleaf.cc)

Objects that describe one or more potential socket endpoints
implement 'GI.Gio.Interfaces.SocketConnectable.SocketConnectable'. Callers can then use
'GI.Gio.Interfaces.SocketConnectable.socketConnectableEnumerate' to get a 'GI.Gio.Objects.SocketAddressEnumerator.SocketAddressEnumerator'
to try out each socket address in turn until one succeeds, as shown
in the sample code below.


=== /C code/
>
>MyConnectionType *
>connect_to_host (const char    *hostname,
>                 guint16        port,
>                 GCancellable  *cancellable,
>                 GError       **error)
>{
>  MyConnection *conn = NULL;
>  GSocketConnectable *addr;
>  GSocketAddressEnumerator *enumerator;
>  GSocketAddress *sockaddr;
>  GError *conn_error = NULL;
>
>  addr = g_network_address_new (hostname, port);
>  enumerator = g_socket_connectable_enumerate (addr);
>  g_object_unref (addr);
>
>  // Try each sockaddr until we succeed. Record the first connection error,
>  // but not any further ones (since they'll probably be basically the same
>  // as the first).
>  while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
>    {
>      conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
>      g_object_unref (sockaddr);
>    }
>  g_object_unref (enumerator);
>
>  if (conn)
>    {
>      if (conn_error)
>        {
>          // We couldn't connect to the first address, but we succeeded
>          // in connecting to a later address.
>          g_error_free (conn_error);
>        }
>      return conn;
>    }
>  else if (error)
>    {
>      /// Either initial lookup failed, or else the caller cancelled us.
>      if (conn_error)
>        g_error_free (conn_error);
>      return NULL;
>    }
>  else
>    {
>      g_error_propagate (error, conn_error);
>      return NULL;
>    }
>}

-}

#define ENABLE_OVERLOADING (MIN_VERSION_haskell_gi_overloading(1,0,0) \
       && !defined(__HADDOCK_VERSION__))

module GI.Gio.Interfaces.SocketConnectable
    ( 

-- * Exported types
    SocketConnectable(..)                   ,
    noSocketConnectable                     ,
    IsSocketConnectable                     ,
    toSocketConnectable                     ,


 -- * Methods
-- ** enumerate #method:enumerate#

#if ENABLE_OVERLOADING
    SocketConnectableEnumerateMethodInfo    ,
#endif
    socketConnectableEnumerate              ,


-- ** proxyEnumerate #method:proxyEnumerate#

#if ENABLE_OVERLOADING
    SocketConnectableProxyEnumerateMethodInfo,
#endif
    socketConnectableProxyEnumerate         ,


-- ** toString #method:toString#

#if ENABLE_OVERLOADING
    SocketConnectableToStringMethodInfo     ,
#endif
    socketConnectableToString               ,




    ) where

import Data.GI.Base.ShortPrelude
import qualified Data.GI.Base.ShortPrelude as SP
import qualified Data.GI.Base.Overloading as O
import qualified Prelude as P

import qualified Data.GI.Base.Attributes as GI.Attributes
import qualified Data.GI.Base.ManagedPtr as B.ManagedPtr
import qualified Data.GI.Base.GClosure as B.GClosure
import qualified Data.GI.Base.GError as B.GError
import qualified Data.GI.Base.GVariant as B.GVariant
import qualified Data.GI.Base.GValue as B.GValue
import qualified Data.GI.Base.GParamSpec as B.GParamSpec
import qualified Data.GI.Base.CallStack as B.CallStack
import qualified Data.GI.Base.Properties as B.Properties
import qualified Data.Text as T
import qualified Data.ByteString.Char8 as B
import qualified Data.Map as Map
import qualified Foreign.Ptr as FP
import qualified GHC.OverloadedLabels as OL

import qualified GI.GObject.Objects.Object as GObject.Object
import {-# SOURCE #-} qualified GI.Gio.Objects.SocketAddressEnumerator as Gio.SocketAddressEnumerator

-- interface SocketConnectable 
-- | Memory-managed wrapper type.
newtype SocketConnectable = SocketConnectable (ManagedPtr SocketConnectable)
-- | A convenience alias for `Nothing` :: `Maybe` `SocketConnectable`.
noSocketConnectable :: Maybe SocketConnectable
noSocketConnectable = Nothing

#if ENABLE_OVERLOADING
type instance O.SignalList SocketConnectable = SocketConnectableSignalList
type SocketConnectableSignalList = ('[ '("notify", GObject.Object.ObjectNotifySignalInfo)] :: [(Symbol, *)])

#endif

foreign import ccall "g_socket_connectable_get_type"
    c_g_socket_connectable_get_type :: IO GType

instance GObject SocketConnectable where
    gobjectType = c_g_socket_connectable_get_type
    

-- | Type class for types which can be safely cast to `SocketConnectable`, for instance with `toSocketConnectable`.
class (GObject o, O.IsDescendantOf SocketConnectable o) => IsSocketConnectable o
instance (GObject o, O.IsDescendantOf SocketConnectable o) => IsSocketConnectable o

instance O.HasParentTypes SocketConnectable
type instance O.ParentTypes SocketConnectable = '[GObject.Object.Object]

-- | Cast to `SocketConnectable`, for types for which this is known to be safe. For general casts, use `Data.GI.Base.ManagedPtr.castTo`.
toSocketConnectable :: (MonadIO m, IsSocketConnectable o) => o -> m SocketConnectable
toSocketConnectable = liftIO . unsafeCastTo SocketConnectable

#if ENABLE_OVERLOADING
instance O.HasAttributeList SocketConnectable
type instance O.AttributeList SocketConnectable = SocketConnectableAttributeList
type SocketConnectableAttributeList = ('[ ] :: [(Symbol, *)])
#endif

#if ENABLE_OVERLOADING
#endif

#if ENABLE_OVERLOADING
type family ResolveSocketConnectableMethod (t :: Symbol) (o :: *) :: * where
    ResolveSocketConnectableMethod "bindProperty" o = GObject.Object.ObjectBindPropertyMethodInfo
    ResolveSocketConnectableMethod "bindPropertyFull" o = GObject.Object.ObjectBindPropertyFullMethodInfo
    ResolveSocketConnectableMethod "enumerate" o = SocketConnectableEnumerateMethodInfo
    ResolveSocketConnectableMethod "forceFloating" o = GObject.Object.ObjectForceFloatingMethodInfo
    ResolveSocketConnectableMethod "freezeNotify" o = GObject.Object.ObjectFreezeNotifyMethodInfo
    ResolveSocketConnectableMethod "getv" o = GObject.Object.ObjectGetvMethodInfo
    ResolveSocketConnectableMethod "isFloating" o = GObject.Object.ObjectIsFloatingMethodInfo
    ResolveSocketConnectableMethod "notify" o = GObject.Object.ObjectNotifyMethodInfo
    ResolveSocketConnectableMethod "notifyByPspec" o = GObject.Object.ObjectNotifyByPspecMethodInfo
    ResolveSocketConnectableMethod "proxyEnumerate" o = SocketConnectableProxyEnumerateMethodInfo
    ResolveSocketConnectableMethod "ref" o = GObject.Object.ObjectRefMethodInfo
    ResolveSocketConnectableMethod "refSink" o = GObject.Object.ObjectRefSinkMethodInfo
    ResolveSocketConnectableMethod "runDispose" o = GObject.Object.ObjectRunDisposeMethodInfo
    ResolveSocketConnectableMethod "stealData" o = GObject.Object.ObjectStealDataMethodInfo
    ResolveSocketConnectableMethod "stealQdata" o = GObject.Object.ObjectStealQdataMethodInfo
    ResolveSocketConnectableMethod "thawNotify" o = GObject.Object.ObjectThawNotifyMethodInfo
    ResolveSocketConnectableMethod "toString" o = SocketConnectableToStringMethodInfo
    ResolveSocketConnectableMethod "unref" o = GObject.Object.ObjectUnrefMethodInfo
    ResolveSocketConnectableMethod "watchClosure" o = GObject.Object.ObjectWatchClosureMethodInfo
    ResolveSocketConnectableMethod "getData" o = GObject.Object.ObjectGetDataMethodInfo
    ResolveSocketConnectableMethod "getProperty" o = GObject.Object.ObjectGetPropertyMethodInfo
    ResolveSocketConnectableMethod "getQdata" o = GObject.Object.ObjectGetQdataMethodInfo
    ResolveSocketConnectableMethod "setData" o = GObject.Object.ObjectSetDataMethodInfo
    ResolveSocketConnectableMethod "setProperty" o = GObject.Object.ObjectSetPropertyMethodInfo
    ResolveSocketConnectableMethod l o = O.MethodResolutionFailed l o

instance (info ~ ResolveSocketConnectableMethod t SocketConnectable, O.MethodInfo info SocketConnectable p) => OL.IsLabel t (SocketConnectable -> p) where
#if MIN_VERSION_base(4,10,0)
    fromLabel = O.overloadedMethod (O.MethodProxy :: O.MethodProxy info)
#else
    fromLabel _ = O.overloadedMethod (O.MethodProxy :: O.MethodProxy info)
#endif

#endif

-- method SocketConnectable::enumerate
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "connectable", argType = TInterface (Name {namespace = "Gio", name = "SocketConnectable"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GSocketConnectable", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
-- Lengths : []
-- returnType : Just (TInterface (Name {namespace = "Gio", name = "SocketAddressEnumerator"}))
-- throws : False
-- Skip return : False

foreign import ccall "g_socket_connectable_enumerate" g_socket_connectable_enumerate :: 
    Ptr SocketConnectable ->                -- connectable : TInterface (Name {namespace = "Gio", name = "SocketConnectable"})
    IO (Ptr Gio.SocketAddressEnumerator.SocketAddressEnumerator)

{- |
Creates a 'GI.Gio.Objects.SocketAddressEnumerator.SocketAddressEnumerator' for /@connectable@/.

/Since: 2.22/
-}
socketConnectableEnumerate ::
    (B.CallStack.HasCallStack, MonadIO m, IsSocketConnectable a) =>
    a
    {- ^ /@connectable@/: a 'GI.Gio.Interfaces.SocketConnectable.SocketConnectable' -}
    -> m Gio.SocketAddressEnumerator.SocketAddressEnumerator
    {- ^ __Returns:__ a new 'GI.Gio.Objects.SocketAddressEnumerator.SocketAddressEnumerator'. -}
socketConnectableEnumerate connectable = liftIO $ do
    connectable' <- unsafeManagedPtrCastPtr connectable
    result <- g_socket_connectable_enumerate connectable'
    checkUnexpectedReturnNULL "socketConnectableEnumerate" result
    result' <- (wrapObject Gio.SocketAddressEnumerator.SocketAddressEnumerator) result
    touchManagedPtr connectable
    return result'

#if ENABLE_OVERLOADING
data SocketConnectableEnumerateMethodInfo
instance (signature ~ (m Gio.SocketAddressEnumerator.SocketAddressEnumerator), MonadIO m, IsSocketConnectable a) => O.MethodInfo SocketConnectableEnumerateMethodInfo a signature where
    overloadedMethod _ = socketConnectableEnumerate

#endif

-- method SocketConnectable::proxy_enumerate
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "connectable", argType = TInterface (Name {namespace = "Gio", name = "SocketConnectable"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GSocketConnectable", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
-- Lengths : []
-- returnType : Just (TInterface (Name {namespace = "Gio", name = "SocketAddressEnumerator"}))
-- throws : False
-- Skip return : False

foreign import ccall "g_socket_connectable_proxy_enumerate" g_socket_connectable_proxy_enumerate :: 
    Ptr SocketConnectable ->                -- connectable : TInterface (Name {namespace = "Gio", name = "SocketConnectable"})
    IO (Ptr Gio.SocketAddressEnumerator.SocketAddressEnumerator)

{- |
Creates a 'GI.Gio.Objects.SocketAddressEnumerator.SocketAddressEnumerator' for /@connectable@/ that will
return @/GProxyAddresses/@ for addresses that you must connect
to via a proxy.

If /@connectable@/ does not implement
'GI.Gio.Interfaces.SocketConnectable.socketConnectableProxyEnumerate', this will fall back to
calling 'GI.Gio.Interfaces.SocketConnectable.socketConnectableEnumerate'.

/Since: 2.26/
-}
socketConnectableProxyEnumerate ::
    (B.CallStack.HasCallStack, MonadIO m, IsSocketConnectable a) =>
    a
    {- ^ /@connectable@/: a 'GI.Gio.Interfaces.SocketConnectable.SocketConnectable' -}
    -> m Gio.SocketAddressEnumerator.SocketAddressEnumerator
    {- ^ __Returns:__ a new 'GI.Gio.Objects.SocketAddressEnumerator.SocketAddressEnumerator'. -}
socketConnectableProxyEnumerate connectable = liftIO $ do
    connectable' <- unsafeManagedPtrCastPtr connectable
    result <- g_socket_connectable_proxy_enumerate connectable'
    checkUnexpectedReturnNULL "socketConnectableProxyEnumerate" result
    result' <- (wrapObject Gio.SocketAddressEnumerator.SocketAddressEnumerator) result
    touchManagedPtr connectable
    return result'

#if ENABLE_OVERLOADING
data SocketConnectableProxyEnumerateMethodInfo
instance (signature ~ (m Gio.SocketAddressEnumerator.SocketAddressEnumerator), MonadIO m, IsSocketConnectable a) => O.MethodInfo SocketConnectableProxyEnumerateMethodInfo a signature where
    overloadedMethod _ = socketConnectableProxyEnumerate

#endif

-- method SocketConnectable::to_string
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "connectable", argType = TInterface (Name {namespace = "Gio", name = "SocketConnectable"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GSocketConnectable", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
-- Lengths : []
-- returnType : Just (TBasicType TUTF8)
-- throws : False
-- Skip return : False

foreign import ccall "g_socket_connectable_to_string" g_socket_connectable_to_string :: 
    Ptr SocketConnectable ->                -- connectable : TInterface (Name {namespace = "Gio", name = "SocketConnectable"})
    IO CString

{- |
Format a 'GI.Gio.Interfaces.SocketConnectable.SocketConnectable' as a string. This is a human-readable format for
use in debugging output, and is not a stable serialization format. It is not
suitable for use in user interfaces as it exposes too much information for a
user.

If the 'GI.Gio.Interfaces.SocketConnectable.SocketConnectable' implementation does not support string formatting,
the implementation’s type name will be returned as a fallback.

/Since: 2.48/
-}
socketConnectableToString ::
    (B.CallStack.HasCallStack, MonadIO m, IsSocketConnectable a) =>
    a
    {- ^ /@connectable@/: a 'GI.Gio.Interfaces.SocketConnectable.SocketConnectable' -}
    -> m T.Text
    {- ^ __Returns:__ the formatted string -}
socketConnectableToString connectable = liftIO $ do
    connectable' <- unsafeManagedPtrCastPtr connectable
    result <- g_socket_connectable_to_string connectable'
    checkUnexpectedReturnNULL "socketConnectableToString" result
    result' <- cstringToText result
    freeMem result
    touchManagedPtr connectable
    return result'

#if ENABLE_OVERLOADING
data SocketConnectableToStringMethodInfo
instance (signature ~ (m T.Text), MonadIO m, IsSocketConnectable a) => O.MethodInfo SocketConnectableToStringMethodInfo a signature where
    overloadedMethod _ = socketConnectableToString

#endif