Developer

API Reference

ISockPort_RecvMsg()

Brew Release
Brew MP 1.0.2
Description
This function reads data from a datagram socket and records the address of the sender, similarly to ISockPort_RecvFrom(). In addition, it can be used to retrieve extended ICMP error information.
This function always returns immediately with the number of bytes read. If no packets have arrived and the socket is still in a valid state, ISockPort_RecvMsg() will return IPORT_WAIT. ISockPort_Readable() may be used to receive notification of when to try ISockPort_RecvMsg() again.
Prior to performing any socket-specific behavior, ISockPort_RecvMsg() 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.
Parameters
  • po
    []:
    pointer to the ISockPort interface
  • pmh
    []:
    pointer to AEESockMsgHdr, used to pack parameters. The meaning of the members depends on the value of the uFlags parameter (not pmh->uFlags, which is not currently used for input flags). If uFlags is 0 (no flags used):
  • pName
    []:
    [out] a pointer to the address to be filled in (see AEESockAddrStorage)
  • wNameLen
    []:
    [in/out] a pointer to the size of the address. Prior to the call, this size should be initialized to the size of the space that pName points to. Upon return, this size will reflect the number of bytes written into pName.
  • pIov
    []:
    [out] an array of SockIOBlock structures into which data can be read. It is the caller's responsibility to allocate enough space for the received packet.
  • wIovLen
    []:
    [in] specifies the number of entries in the pIov array.
  • pControl
    []:
    Not used.
  • wControlLen
    []:
    Not used.
  • uFlags
    []:
    [out] if the AEE_IP_RECVERR socket option is set, the SOCKPORT_FLAG_RECVMSG_ERRQUEUE flag will be set on return when there are pending ICMP errors. If the uFlags mask contains SOCKPORT_FLAG_RECVMSG_ERRQUEUE (request to retrieve extended ICMP error information, the AEE_IP_RECVERR socket option must be set):
  • pName
    []:
    [out] a pointer to the address to be filled in (see AEESockAddrStorage) - the returned address is the original destination of the datagram that caused the error.
  • wNameLen
    []:
    [in/out] the size of the address. Prior to the call, this size should be initialized to the size of the space that pName points to. Upon return, this size will reflect the number of bytes written into pName.
  • pIov
    []:
    [out] an array of SockIOBlock structures into which data can be read. It is the caller's responsibility to allocate enough space for the received packet. On return, the array will contain the payload of the original packet that caused the error.
  • wIovLen
    []:
    [in] specifies the number of entries in the pIov array.
  • pControl
    []:
    [out] A pointer to AEESockCMsgHdr. Ancillary data - the extended error information. Only one error is returned in the data section of the AEESockCMsgHdr, the error is of the type AEEICMPErrMsg.
  • wControlLen
    []:
    [in/out] the size of pControl in bytes. To retrieve all the extended error information, the size should be at least AEESOCKCMSG_SPACE(sizeof(AEEICMPErrMsg)). On return, this field will contain the number of bytes written into pControl.
  • uFlags
    []:
    [out] the SOCKPORT_FLAG_RECVMSG_ERRQUEUE flag will be set on return when there are more pending ICMP errors. The SOCKPORT_FLAG_RECVMSG_MSGTRUNC flag will be set on return when the ancillary data was truncated due to lack of space.
  • uFlags
    []:
    currently, only the SOCKPORT_FLAG_RECVMSG_ERRQUEUE flag is supported (see pmh for details).
Interface
Prototype
   int ISockPort_RecvMsg(ISockPort *po, AEESockMsgHdr *pmh, uint32 uFlags)
Return

bytes_read (>=0) : any non-negative number indicates a number of bytes that have been successfully read into the provided buffer
IPORT_WAIT : no data available now; try again later. (See ISockPort_Readable())
IPORT_ERROR : the specific error code can be retrieved by calling ISockPort_GetLastError():
  • AEE_NET_EBADF : socket is not open
  • 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_EADDRINUSE: attempted to bind to local port already in use
  • AEE_NET_EFAULT : invalid pcBuf pointer
  • AEE_NET_EINVAL : socket not bound

  • The following error codes can be returned in case there is no data to read,
  • 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. Specified by Posix.1g.
  • Follow