Use this API to communicate with your Lyric device and send SMS using its SIM Cards and handle the received messages. You will be usually using 2 classes: cl.yx.YX_Session and cl.yx.YX_SMSConnector. A cl.yx.YX_Session object must be instantiated using username, password, and a cl.yx.YX_SMSConnector object, which specifies the IP address (and internally, the port) to use when connecting to the device.
If a YX_Session object has been instantiated properly - using the right credentials and the right permissions -- you can then send an SMS using one of the 3 sendMsg() methods provided.
The sendMsg() methods block until an answer is received or a timeout occurs. We also provide a queueMsg() method which does not block. See more in the next section.
Send the same message to 25 recipients, 10 seconds timeout.
public class SMSTest { public static void main(String args[]) { try { int timeout = 10; YX_Session s = new YX_Session("username", "password", new YX_SMSConnector("host")); for (int i = 0; i < 25; i++) { System.out.println( "------------------ Test " + i ); try { s.sendMsg("Hey, let's talk soon", friend_number[i], timeout, new YX_PrintNotifier()); } catch (YX_TimeoutException e) { System.out.println( "Timeout while waiting for delivery, Aborting"); break; } catch (YX_DataException e) { System.out.println( "Protocol problem. Do we have the latest API available??"); break; } catch (YX_AuthenticationException e) { System.out.println("Authentication problem. Check user or password"); break; } catch (YX_UserPrivilegeException e) { System.out.println("User does not have enough privileges"); break; } catch (YX_ServerProblemException e) { System.out.println("Server problems"); break; } // ... } } catch (YX_IOException e) { // TODO: Connectivity problem scenario e.printStackTrace(); } } }
The above source code may be used as the base for an advertising campaign using SMS. Other examples (not shown here) may be: Send different messages to the same recipient (e.g. hourly news, stock quotes, horoscope, etc), send alarms for certain events, etc.
The Exception classes shown above extend the base class YX_Exception. If you prefer to handle all exception in one place the code could have been written like this instead:
public class SMSTest { public static void main(String args[]) { try { int timeout = 10; YX_Session s = new YX_Session("username", "password", new YX_SMSConnector("host")); for (int i = 0; i < 25; i++) { System.out.println( "------------------ Test " + i ); try { s.sendMsg("Hey, let's talk soon", friend_number[i], timeout, new YX_PrintNotifier()); } catch (YX_Exception e) { System.out.println( "Exception occurred. Aborting"); break; } // ... } } catch (YX_IOException e) { // TODO: Connectivity problem scenario e.printStackTrace(); } } }
As mentioned before, the API also provides a queueMsg() method, which is used whenever you want to send the SMS, but you do not want to block until the message is delivered. This method returns a ticket which can be used later to request information on the delivery status.
There are two ways to retrieve the delivery status: Polling for information and registering a notifier. The first example suggest a way to poll for the status, while the second one illustrates both methods. The current API version supports the first method.
Send a message and do not wait, with 30 seconds timeout.
try { String status; YX_Session s = new YX_Session("username", "password", new YX_SMSConnector("host")); // queue message, with a 30 seconds timeout try { int timeout = 30; YX_Ticket t = s.queueMsg("hi friend, see you later", "12341234", timeout); // sometime later // ... if (t != null) { status = s.requestStatus(t, 30); while(status != "done") { System.out.println("Ticket " + t + " status: " + status); status = s.requestStatus(t, 30); } } } catch (YX_TimeoutException e1) { System.out.println("Timeout while waiting for delivery, Aborting"); } catch (YX_DataException e) { System.out.println("Protocol problem. Do we have the latest API available??"); } catch (YX_AuthenticationException e) { System.out.println("Authentication problem. Check user or password"); } catch (YX_UserPrivilegeException e) { System.out.println("User does not have enough privileges"); } catch (YX_ServerProblemException e) { System.out.println("Server problems"); } } catch (YX_IOException e) { // Trying to connect to Lyric failed e.printStackTrace(); }
Send a message and do not wait, with 30 seconds timeout.
To be able to be informed when a message has been delivered (or has changed state), you should call the initNotificationServer() method first. Then you may call the requestStatus() method with the ticket that you receive to poll for information on that ticket. If you prefer not to poll but to be called back when there is a change, use the registerNotifier() method instead.
When initNotificationServer( int port ) method is called, it will open the specified IP port. The Lyric device will try to contact the API through this port. The notification process will fail if this service is not available for the Lyric to use. If you have a firewall blocking inbound connections, you may need to specify an exception for the specified IP port.
try { YX_Session s = new YX_Session("username", "password", new YX_SMSConnector("host")); int port = 9870; YX_NotificationServer ns = s.initNotificationServer(port); // you may check, at any moment, for NotificationServer's health using something like if( ns != null && ns.connectionOk() == false ) ns.restartService(); // queue message, with a 30 seconds timeout try { int timeout = 30; YX_Ticket t = s.queueMsg("hi friend, see you later", "5551234", timeout); // sometime later // ... if (t != null) { // Method 1: Poll for information (could be a loop also) System.out.println("Ticket " + t + " status: " + s.requestStatus(t)); // Method 2: Register a notifier, continue executing and let // notifier's notify( String ) method to do what you want WindowNotifier w = new WindowNotifier(); s.registerNotifier(t, w); // continue execution.. } } catch (YX_TimeoutException e1) { System.out.println("Timeout while waiting for delivery, Aborting"); } catch (YX_DataException e) { System.out.println("Protocol problem. Do we have the latest API available??"); } catch (YX_AuthenticationException e) { System.out.println("Authentication problem. Check user or password"); } catch (YX_UserPrivilegeException e) { System.out.println("User does not have enough privileges"); } catch (YX_ServerProblemException e) { System.out.println("Server problems"); } } catch (YX_IOException e) { // Trying to connect to Lyric failed e.printStackTrace(); } catch (YX_NotificationServerNotInitialized e) { // Trying to use a queueMsg related method, but with no NotificationServer? e.printStackTrace(); }
One may also request the date on which a message was sent. The following example shows how this is achieved. Also, it shows how a YX_Ticket object may be created and how a YX_Date object is handled.
try { int ticket_n = 1192; YX_Session s = new YX_Session("username", "password", new YX_SMSConnector("host")); YX_Ticket t = new YX_Ticket(ticket_n); YX_SMS_Status sms_stat = s.requestCompleteStatus(t, timeout); if ( sms_stat != null ) { String status = sms_stat.getStatus(); YX_Date date = sms_stat.getDate(); System.out.println("Estado ticket " + ticket_n + ": " + status); if ( date != null ) { System.out.println("Send date: " + date); } else { System.out.println("Message with ticket " + ticket_n + " has not been sent yet."); } } else { System.out.println("Couldn't retrieve status!"); } } catch (YX_IOException e) { System.out.println("Not connected to the device"); } catch (YX_TimeoutException e) { System.out.println( "Timeout while waiting for delivery, Aborting"); } catch (YX_DataException e) { System.out.println( "Protocol problem. Do we have the latest API available??"); } catch (YX_AuthenticationException e) { System.out.println("Authentication problem. Check user or password"); } catch (YX_UserPrivilegeException e) { System.out.println("User does not have enough privileges"); } catch (YX_ServerProblemException e) { System.out.println("Server problems"); }
The version 0.4 of the Java API introduces a set of functions to handle received messages. Now it's possible to get to know the number of received messages by the device, retrieve a certain number of the first or last received messages and set their status as read.
The following example shows how to obtain half of the last messages received and print their content.
try { YX_Session s = new YX_Session("username", "password", new YX_SMSConnector("host")); int half = s.getNumberRecvMsg() / 2; Vector<YX_ReceivedMessage> v = s.getLastNRecvMsg(half); YX_ReceivedMessage tmp; if ( v != null ) { for (int i = 0; i < v.size(); i++) { tmp = v.get(i); System.out.println(tmp.getMessage()); } } } catch( ... ) { // ... }
The following example shows how to set a message read specifying its ID. The status of the message in the device database is set to "read" and its "read date" to the moment it was set.
try { YX_Session s = new YX_Session("username", "password", new YX_SMSConnector("host")); int id = 350; s.setReadRecvMsg(id); } catch( ... ) { // ... }
To be notified when an inbound SMS arrives, use the registerNotifier() method, with the special ticket YX_Ticket.SMSIn().
s.registerNotifier( YX_Ticket.SMSIn(), your_notifier );
1.6.3
