Developer

API Reference

ISockPort_SendTo()

Brew Release
Brew MP 1.0.2
See Also
None.
Description
This function sends a datagram packet to the specified address from the local address bound to the socket. This function must be used with sockets of type AEE_SOCKPORT_DGRAM -- not with sockets of type AEE_SOCKPORT_STREAM. If the socket has not been bound to a local address, this function will bind it to a local address.
Sockets always operate in non-blocking mode. This function returns immediately and, if successful, returns the number of bytes written. If no bytes could be successfully sent and the connection is still active, the function will return IPORT_WAIT. To be notified when to call ISockPort_SendTo() again, the caller should call ISockPort_Writeable().
For an AEE_AF_INET or AEE_AF_INET6 datagram socket, ISockPort_SendTo() can be used on multiple interfaces (e.g. BREW Loopback and PPP) for the same socket. In this case, ISockPort_Writeable() is tied to the previous call to ISockPort_SendTo(). If ISockPort_SendTo() has never been called, ISockPort_Writeable() is tied to all available interfaces.
AEE_AF_LOCAL: Currently AEE_AF_LOCAL is not supported.
AEE_AF_INET and AEE_AF_INET6: Prior to performing any socket-specific behavior, ISockPort_SendTo() will try to acquire an IP address and ensure the underlying network layer is ready for communication. This may involve the establishment of an Internet connection using CDMA Packet Data or QNC if such a connection has not already been established. Finally, any previously-requested ISockPort_Bind() operation will be attempted if necessary. As a result, errors relating to network startup or ISockPort_Bind() could be reported here, and IPORT_WAIT return values are commonly encountered.
Two flags are supported for the SendTo operation on UDP sockets: - ISockPort_FLAG_SENDTO_URGENT flag will attempt to deliver the message even
if the network is asleep (e.g. on a common channel instead of a dedicated channel). There will probably be limits on the size of such signaling, even if it is supported. See the INetwork_GetOpt() function for details. This feature should be used with discretion, and requires a privilege: NET_URGENT must be specified as an external dependency in the application's MIF in order to utilize this option. It will be useful for applications with very low bandwidth requirements or applications which are sensitive to the additional network delay of waiting for the network to be awakened from dormancy. - ISockPort_FLAG_SENDTO_WAKEUP flag can be used in conjunction with the ISockPort_FLAG_SENDTO_URGENT
flag to concurrently request that the network should be awakened from dormancy as soon as possible, subsequent to the message delivery. If only the ISockPort_FLAG_SENDTO_WAKEUP is set, UDP data will NOT be sent. This feature requires System privileges.
Parameters
  • po
    []:
    pointer to the ISockPort interface
  • pcBuf
    []:
    buffer of data to send
  • cbBuf
    []:
    size of the buffer, in bytes
  • dwFlags
    []:
    Data transport
  • pAddr
    []:
    an opaque pointer to the address to send to (see AEESockAddrStorage)
Interface
Prototype
   int32 ISockPort_SendTo(ISockPort* po, const char* pcBuf, int32 cbBuf,
                          uint32 dwFlags, const void* pAddr)
Return

bytes_sent (>0) : any positive number indicates the number of bytes successfully sent.
IPORT_WAIT : Cannot send data at this time; try again later. (See ISockPort_Writeable())
IPORT_ERROR : the specific error code can be retrieved by calling ISockPort_GetLastError():
  • AEE_NET_EBADF : socket is not open
  • AEE_NET_EAFNOSUPPORT: not an inet address
  • AEE_NET_EMFILE : not enough resources to complete
  • this operation (too many sockets are in use).
  • AEE_NET_ENETDOWN : network is not available (e.g. handset is outside
  • of coverage area)
  • AEE_NET_EOPNOTSUPP : not a datagram socket
  • AEE_NET_EFAULT : invalid pcBuf pointer
  • AEE_NET_ENOMEM : not enough memory
  • AEE_NET_EINVAL : socket not bound
  • EPRIVLEVEL : no privileges to use URGENT or WAKEUP flags

  • The following error codes can be returned in case the AEE_SO_ERROR_ENABLE
  • socket option is enabled and there is a pending ICMP error for the socket:

  • AEE_NET_ENETUNREACH : network is unreachable
  • AEE_NET_EHOSTUNREACH: host is unreachable
  • AEE_NET_EHOSTDOWN : host is down
  • AEE_NET_ENONET : host is not on the network
  • AEE_NET_EPROTO : protocol error
  • AEE_NET_EACCES : access denied
  • AEE_NET_ENOPROTOOPT : protocol unreachable
  • AEE_NET_ECONNREFUSED: port unreachable
  • AEE_NET_EMSGSIZE : message too large
  • AEE_NET_EOPNOTSUPP : operation not supported

  • Other error codes are also possible.
Side Effect
None.
Comment
Note that the IPORT_WAIT return value is used instead of an error return value and an AEE_NET_EWOULDBLOCK error code.
  • Follow