Package kr.ac.konkuk.ccslab.cm.stub

Class CMClientStub

java.lang.Object
kr.ac.konkuk.ccslab.cm.stub.CMStub
kr.ac.konkuk.ccslab.cm.stub.CMClientStub
public class CMClientStub extends CMStub
This class provides APIs, through which a client developer can access most of the communication services of CM. A client application can use this class in order to request client-specific communication services.
See Also:

  • Constructor Details

    • CMClientStub

      public CMClientStub()
      Creates an instance of the CMClientStub class.

      This method just called the default constructor of the super class, CMStub.

  • Method Details

    • setTransferedFileHome

      public boolean setTransferedFileHome(Path dir)
      Sets the default file path for file transfer.
      This method updates the transfered-file path information in CM and the FILE_PATH field in the CM configuration file.

      CM applications that directly connect to each other can exchange a file with the CMStub class that is the parent class of the CMClientStub and the CMServerStub classes. In the client-server architecture, a client can push or pull a file to/from a server and vice versa. When CM is initialized by an application, the default directory is configured by the path information that is set in the configuration file (the FILE_PATH field). If the default directory does not exist, CM creates it. If the FILE_PATH field is not set, the default path is set to the current working directory (".").

      If the file transfer is requested, a sender (the server or the client) searches for the file in the default file path. If a client receives a file, CM stores the file in this file path. If a server receives a file, CM stores the file in a sub-directory of the default path. The sub-directory name is a sender (client) name.

      Parameters:
      dir - - the file path
      Returns:
      true if the file path is successfully updated both in the CMConfigurationInfo class and the configuration file (cm-client.conf), or false otherwise.
      See Also:

    • setServerAddress

      public boolean setServerAddress(String strAddress)
      Sets server address to the client configuration file.

      This method must be called before an application starts CM because it updates the value of "SERVER_ADDR" field in the client configuration file (cm-client.conf).

      Parameters:
      strAddress - - the server IP address
      Returns:
      true if the server address is successfully set, or false otherwise.
      See Also:

    • getServerAddress

      public String getServerAddress()
      Gets server address from the client configuration file.
      Returns:
      server address
      See Also:

    • setServerPort

      public boolean setServerPort(int nPort)
      Sets server port number to the client configuration file.

      This method must be called before an application starts CM because it updates the value of "SERVER_PORT" field in the client configuration file (cm-client.conf).

      Parameters:
      nPort - - the server port number
      Returns:
      true if the server port is successfully set, or false otherwise.
      See Also:

    • getServerPort

      public int getServerPort()
      Gets server port number from the client configuration file.
      Returns:
      server port number
      See Also:

    • setServerInfo

      public boolean setServerInfo(String strAddress, int nPort)
      Sets server address and port number to the client configuration file.

      This method must be called before an application starts CM because it updates the values of "SERVER_ADDR" and "SERVER_PORT" fields in the client configuration file (cm-client.conf).

      Parameters:
      strAddress - - the server IP address
      nPort - - the server port number
      Returns:
      true if the server address and port number are successfully set, or false otherwise.
      See Also:

    • startCM

      public boolean startCM()
      Initializes and starts the client CM.

      Before the server CM starts, it initializes the configuration and the interaction manager. Then, it starts two separate threads for receiving and processing CM events.
      After the initialization process, the client CM also establishes a stream(TCP) connection to the default server and makes a default datagram(UDP) channel.

      Returns:
      true if the initialization of CM succeeds, or false if the initialization of CM fails.
      See Also:

    • terminateCM

      public void terminateCM()
      Terminates the client CM.
      A client application calls this method when it does not need to use CM. The client releases all the resources, logs out from the server, and disconnects all communication channels.
      Overrides:
      terminateCM in class CMStub
      See Also:

    • connectToServer

      public boolean connectToServer()
      Connects to the default server.

      When a client application calls this method, the client CM opens a default stream(TCP) channel and connects to the server CM used by the default server application.
      When the CM client starts by calling the startCM() method, it connects to the default server ("SERVER") as one of the initialization tasks. Before the client logs in to the default CM server, it must be connected to the server by calling this method. The connection to the default server is made with the default TCP channel.

      Returns:
      true if the connection is established successfully, or false otherwise.
      See Also:

    • disconnectFromServer

      public boolean disconnectFromServer()
      Disconnects from the default server.
      When a client application calls this method, the client CM tries to disconnect all the stream(TCP) channels from the server CM used by the default server application.
      Returns:
      true if the connection is successfully disconnected, or false otherwise.
      See Also:

    • loginCM

      public boolean loginCM(String strUserName, String strPassword)
      Logs in to the default server.
      For logging in to the server, the client first needs to register to the server by calling registerUser() method.

      The result of the login request can be caught asynchronously by the client event handler that deals with all the incoming CM events from the server. To check whether the login request is successful or not, the client event handler needs to catch the CMSessionEvent.LOGIN_ACK event. In the LOGIN_ACK event, a result field of the Integer type is set, and the value can be retrieved by the CMSessionEvent.isValidUser() method. If the value is 1, the login request successfully completes and the requesting client is in the CM_LOGIN state. Otherwise, the login process fails. The LOGIN_ACK event also includes other CM information that can be returned by CMSessionEvent.getCommArch(), CMSessionEvent.isLoginScheme(), and CMSessionEvent.isSessionScheme().

      When the server CM accepts the login request from a client, the server CM also notifies other participating clients of the information of the login user with the CMSessionEvent.SESSION_ADD_USER event. A client application can catch this event in the event handler routine if it wants to use such information. The login user information is the user name and the host address that can be retrieved by CMSessionEvent.getUserName() and CMSessionEvent.getHostAddress() methods, respectively.

      Parameters:
      strUserName - - the user name
      strPassword - - the password
      Returns:
      true if the request is successfully sent to the server; false otherwise.
      See Also:

    • syncLoginCM

      public CMSessionEvent syncLoginCM(String strUserName, String strPassword)
      Logs in to the default server synchronously.

      Unlike the asynchronous login method (loginCM(String, String)), this method makes the main thread of the client block its execution until it receives and returns the reply event (CMSessionEvent.LOGIN_ACK) from the default server.
      For the other detailed information of the login process, please refer to the asynchronous login method.

      Parameters:
      strUserName - - the user name
      strPassword - - the password
      Returns:
      the reply event (CMSessionEvent.LOGIN_ACK) from the default server.
      See Also:

    • logoutCM

      public boolean logoutCM()
      Logs out from the default server.

      There is no result from the server about the logout request.

      When the server CM completes the logout request from a client, the server CM also notifies other participating clients of the information of the logout user with the CMSessionEvent.SESSION_REMOVE_USER event. A client application can catch this event in the event handler routine if it wants to use such information. The logout user information is just the user name, which can be returned by CMSessionEvent.getUserName() method.

      Returns:
      true if successfully sent the logout request, false otherwise.
      See Also:

    • requestSessionInfo

      public boolean requestSessionInfo()
      Requests available session information from the default server.
      For requesting the session information, the client first needs to log in to the server by calling loginCM() method.

      The result of the session request can be caught asynchronously by the client event handler that deals with all the incoming CM events from the server. To receive the available session information, the client event handler needs to catch the CMSessionEvent.RESPONSE_SESSION_INFO event.
      The RESPONSE_SESSION_INFO event includes the number of available sessions and the vector of the CMSessionInfo. Such event fields can be returned by the CMSessionEvent.getSessionNum() and CMSessionEvent.getSessionInfoList().
      Each element of the CMSessionInfo object includes information of an available session such as the session name, the session address and port number to which a client can join, and the current number of session members who already joined the session.

      Returns:
      true if the request is successfully sent to the server; false otherwise.
      See Also:

    • syncRequestSessionInfo

      public CMSessionEvent syncRequestSessionInfo()
      Requests available session information from the default server synchronously.

      Unlike the asynchronous method (requestSessionInfo()), this method makes the main thread of the client block its execution until it receives and returns the reply event (CMSessionEvent.RESPONSE_SESSION_INFO) from the default server.
      For the other detailed information of the session-information-request process, please refer to the asynchronous version of the request.

      Returns:
      the reply event (CMSessionEvent.RESPONSE_SESSION_INFO) from the default server.
      See Also:

    • joinSession

      public boolean joinSession(String sname)
      Joins a session in the default server.
      For joining a session, the client first needs to log in to the server by calling loginCM() method. The client can get available session information by calling the requestSessionInfo() method.

      After the login process has completed, a client application must join a session and a group of CM to finish entering the CM network. The session join process is different according to whether the server CM adopts single session or multiple sessions in the CM server configuration file (cm-server.conf).

      When the server CM receives the join-session request, it sends back the client a reply event (CMSessionEvent.JOIN_SESSION_ACK) that contains the group information in the session. If the reply event does not have any group information, it implies that the join-session task fails because every session in CM must has at least one group.

      After the client CM completes to join a session, it automatically proceeds to enter the first group of the session. For example, if the client joins "session1", it also enters the group, "g1" that is the first group of the session, "session1".

      When the server CM completes the session joining request from a client, the server CM also notifies other participating clients of the information of the new session user with the CMSessionEvent.CHANGE_SESSION event. A client application can catch this event in the event handler routine if it wants to use such information. The CHANGE_SESSION event includes fields such as the user name and the session name, which can be returned by calling the CMSessionEvent.getUserName() and the CMSessionEvent.getSessionName() methods, respectively.

      When the server CM completes the group joining request from a client, the server CM also notifies other participating clients of the information of the new group user with the CMDataEvent.NEW_USER event. When the client CM receives this event, it stores the information of a new group user so that it can figure out current group members later. A client application also can catch this event in the event handler routine if it wants to use such information. The NEW_USER event includes fields such as the current session name, the current group name, the name of the new group user, the host address of the new group user, and the UDP port number of the new group user. Each event field can be returned by calling the CMEvent.getHandlerSession(), CMEvent.getHandlerGroup(), CMDataEvent.getUserName(), CMDataEvent.getHostAddress(), and CMDataEvent.getUDPPort() methods, respectively.

      When the server CM completes the group joining request from a client, the server CM also notifies the new user of the information of other existing group users with the series of CMDataEvent.INHABITANT events. When the client CM receives this event, it stores the information of an existing group user so that it can figure out current group members later. A client application also can catch this event in the event handler routine if it wants to use such information. The INHABITANT event includes fields such as the current session name, the current group name, the name of the new group user, the host address of the new group user, and the UDP port number of the new group user. Each event field can be returned by calling the CMEvent.getHandlerSession(), CMEvent.getHandlerGroup(), CMDataEvent.getUserName(), CMDataEvent.getHostAddress(), and CMDataEvent.getUDPPort() methods, respectively.

      Parameters:
      sname - - the session name that a client requests to join
      Returns:
      true if the request is successful; false otherwise.
      See Also:

    • syncJoinSession

      public CMSessionEvent syncJoinSession(String sname)
      Joins a session in the default server synchronously.

      Unlike the asynchronous method (joinSession(String)), this method makes the main thread of the client block its execution until it receives and returns the reply event (CMSessionEvent.JOIN_SESSION_ACK) from the default server.
      For the other detailed information of the session-join process, please refer to the asynchronous version of the request.

      Parameters:
      sname - - the session name that a client requests to join
      Returns:
      the reply event (CMSessionEvent.JOIN_SESSION_ACK) from the default server, null if the request fails.
      See Also:

    • leaveSession

      public boolean leaveSession()
      Leaves the current session in the default server.

      There is no result from the server about the session-leave request.

      Before leaving the current session, the server first remove the client from its current group. The server notifies group members of the user leave by sending the CMDataEvent.REMOVE_USER event. The REMOVE_USER event includes the user name field, which can be returned by the CMDataEvent.getUserName() method.

      When the server CM completes the session leaving request from a client, the server CM also notifies other participating clients of the information of the leaving user with the CMSessionEvent.CHANGE_SESSION event. A client application can catch this event in the event handler routine if it wants to use such information. The CHANGE_SESSION event includes fields such as the user name and the session name, which can be returned by calling the CMSessionEvent.getUserName() and the CMSessionEvent.getSessionName() methods, respectively. If the session name field of this event is an empty space, a client can know that the user leaves his/her current session.

      Returns:
      true if successfully sent the leave-session request, false otherwise.
      See Also:

    • sendUserPosition

      public void sendUserPosition(CMPosition pq)
      Sends location information of the client to the group members.

      The location information consists of the position and orientation. The position is represented by 3D coordinate (x,y,z). The orientation is represented by the quaternion (x,y,z,w) that includes the rotation axis and the rotation angle.

      Parameters:
      pq - - the new position and orientation of the client
      See Also:

    • chat

      public void chat(String strTarget, String strMessage)
      Sends a chat event.

      A CM application can receive the chat event by catching a pre-defined CM event in the event handler like other events. There are two types of CM chat events. One is the CMSessionEvent.SESSION_TALK event. A client can receive this event if it at least logs in to the default server. The SESSION_TALK event includes fields such as the sender name, the text message, and the session name of the sender, which can be returned by calling CMSessionEvent.getUserName(), CMSessionEvent.getTalk(), and CMEvent.getHandlerSession() methods, respectively.
      The other event is the CMInterestEvent.USER_TALK event. A client can receive this event only if it enters a group. The USER_TALK event includes fields such as the sender name, the text message, the session name of the sender, and the group name of the sender, which can be returned by calling CMInterestEvent.getUserName(), CMInterestEvent.getTalk(), CMEvent.getHandlerSession(), and CMEvent.getHandlerGroup() methods, respectively.

      Parameters:
      strTarget - - the receiver name.
      This parameter must start with "/" character and it specifies the range of recipients of the chat message as described below:
      /b - The chat message is sent to the all login users.
      /s - The chat message is sent to the all session members of the sending user.
      /g - The chat message is sent to the all group members of the sending user.
      /name - The chat message is sent to a specific CM node of which name is "name". The name can be another user name or a server name. If "name" is SERVER, the message is sent to the default server.
      strMessage - - the chat message.

    • changeGroup

      public void changeGroup(String gName)
      Changes the current group of the client.

      When a client calls this method, the client first leaves the current group and then requests to enter a new group. The CM server notifies previous group members of the left user by sending the CMDataEvent.REMOVE_USER event, and the server also notifies new group members of the new user by sending the CMDataEvent.NEW_USER event. The server also notifies the changing user of the existing member information of the new group by sending the CMDataEvent.INHABITANT event.

      Parameters:
      gName - - the name of a group that the client wants to enter.
      See Also:

    • addNonBlockSocketChannel

      public boolean addNonBlockSocketChannel(int nChKey, String strServer)
      Adds asynchronously a nonblocking (TCP) socket channel to a server.
      Only the client can add an additional stream socket (TCP) channel. In the case of the datagram and multicast channels, both the client and the server can add an additional non-blocking channel with the CMStub.addNonBlockDatagramChannel(int) and CMStub.addMulticastChannel(String, String, String, int) methods in the CMStub class.

      Although this method returns the reference to the valid socket channel at the client, it is unsafe for the client to use the socket before the server also adds the relevant channel information. The establishment of a new nonblocking socket channel at both sides (the client and the server) completes only when the client receives the ack event (CMSessionEvent.ADD_NONBLOCK_SOCKET_CHANNEL_ACK) from the server and the return code in the event is 1. The client event handler can catch the ack event.

      Parameters:
      nChKey - - the channel key that must be greater than 0. The key 0 is occupied by the default TCP channel.
      strServer - - the server name to which the client adds a TCP channel. The name of the default server is 'SERVER'.
      Returns:
      true if the socket channel is successfully created at the client and requested to add the (key, socket) pair to the server.
      False, otherwise.
      See Also:

    • syncAddNonBlockSocketChannel

      public SocketChannel syncAddNonBlockSocketChannel(int nChKey, String strServer)
      Adds synchronously a nonblocking (TCP) socket channel to a server.
      Only the client can add an additional stream socket (TCP) channel. In the case of the datagram and multicast channels, both the client and the server can add an additional non-blocking channel with the CMStub.addNonBlockDatagramChannel(int) and CMStub.addMulticastChannel(String, String, String, int) methods in the CMStub class.
      Parameters:
      nChKey - - the channel key which must be greater than 0. The key 0 is occupied by the default TCP channel.
      strServer - - the server name to which the client adds a TCP channel. The name of the default server is 'SERVER'.
      Returns:
      true if the socket channel is successfully created both at the client and the server.
      False, otherwise.
      See Also:

    • removeNonBlockSocketChannel

      public boolean removeNonBlockSocketChannel(int nChKey, String strServer)
      Removes a nonblocking (TCP) socket channel from a server.
      Parameters:
      nChKey - - the key of the channel that is to be removed. The key must be greater than 0. If the default channel (0) is removed, the result is undefined.
      strServer - - the server name from which the additional channel is removed.
      Returns:
      true if the client successfully closes and removes the channel, or false otherwise.
      If the client removes the nonblocking socket channel, the server CM detects the disconnection and removes the channel at the server side as well.
      See Also:

    • addBlockSocketChannel

      public boolean addBlockSocketChannel(int nChKey, String strTarget)
      Adds asynchronously a blocking (TCP) socket channel to a target node (server or client).
      Only the client can add an additional stream socket (TCP) channel. In the case of the datagram channel, both the client and the server can add an additional blocking channel with the CMStub.addBlockDatagramChannel(int) method in the CMStub class.

      Although this method returns the reference to the valid socket channel, the target side socket channel is always created as a nonblocking mode first due to the intrinsic CM architecture of event-driven asynchronous communication. The target sends the acknowledgement message after the nonblocking channel is changed to the blocking channel. It is unsafe for the client use its socket channel before the channel is changed to the blocking mode at the target node. The establishment of a new blocking socket channel at both sides (the client and the target) completes only when the client receives the ack event (CMSessionEvent.ADD_BLOCK_SOCKET_CHANNEL_ACK) from the target and the return code in the event is 1. The client event handler can catch the ack event.

      Parameters:
      nChKey - - the channel key. It should be a positive integer (greater than or equal to 0).
      strTarget - - the name of a target (server or client) to which the client creates a connection.
      Returns:
      a reference to the socket channel if it is successfully created at the client, or null otherwise.
      See Also:

    • syncAddBlockSocketChannel

      public SocketChannel syncAddBlockSocketChannel(int nChKey, String strTarget)
      Adds synchronously a blocking (TCP) socket channel to a target node (server or client).
      Only the client can add an additional stream socket (TCP) channel. In the case of the datagram channel, both the client and the server can add an additional blocking channel with the CMStub.addBlockDatagramChannel(int) method in the CMStub class.
      Parameters:
      nChKey - - the channel key. It should be a positive integer (greater than or equal to 0).
      strTarget - - the name of a target (server or client) to which the client creates a connection.
      Returns:
      a reference to the socket channel if it is successfully created both at the client and the target, or null otherwise.
      See Also:

    • removeBlockSocketChannel

      public boolean removeBlockSocketChannel(int nChKey, String strTarget)
      Removes asynchronously the blocking socket (TCP) channel.

      This method does not immediately remove the requested channel for safe and smooth close procedure between the client and the target node (server or client). Before the removal of the client socket channel, the client first sends a request CM event to the target that then prepares the channel disconnection and sends the ack event (CMSessionEvent.REMOVE_BLOCK_SOCKET_CHANNEL_ACK) back to the client.
      The client closes and removes the target channel only if it receives the ack event and the return code is 1. The client event handler can catch the event in order to figure out the result of the removal request.

      Parameters:
      nChKey - - the key of a socket channel that is to be deleted.
      strTarget - - the name of a target (server or client) to which the target socket channel is connected.
      Returns:
      true if the client successfully requests the removal of the channel from the target, or false otherwise.
      The blocking socket channel is closed and removed only when the client receives the ack event from the target.
      See Also:

    • syncRemoveBlockSocketChannel

      public boolean syncRemoveBlockSocketChannel(int nChKey, String strTarget)
      Removes synchronously the blocking socket (TCP) channel.

      This method does not immediately remove the requested channel for safe and smooth close procedure between the client and the target (server or client). Before the removal of the client socket channel, the client first sends a request CM event to the target that then prepares the channel disconnection and sends the ack event (CMSessionEvent.REMOVE_BLOCK_SOCKET_CHANNEL_ACK) back to the client.
      The client closes and removes the target channel only if it receives the ack event and the return code is 1.

      Parameters:
      nChKey - - the key of a socket channel that is to be deleted.
      strTarget - - the name of a target (server or client) to which the target socket channel is connected.
      Returns:
      true if the client successfully closed and removed the channel, false otherwise.
      The blocking socket channel is closed and removed only when the client receives the ack event from the target.
      See Also:

    • getBlockSocketChannel

      public SocketChannel getBlockSocketChannel(int nChKey, String strServerName)
      Returns a blocking socket (TCP) channel.

      A client can add a blocking socket channel with addBlockSocketChannel(int, String) method, and retrieve it later with this method.

      Parameters:
      nChKey - - the channel key.
      strServerName - - the name of a server to which the socket channel is connected.
      If strServerName is null, it implies the socket channel to the default server.
      Returns:
      the blocking socket channel, or null if the channel is not found.
      See Also:

    • requestSNSContent

      public void requestSNSContent(String strWriter, int nOffset)
      Requests to download the list of SNS content from the default server.

      The number of downloaded content items is determined by the server. In the configuration file of the server CM (cm-server.conf), the DOWNLOAD_NUM field specifies the number of downloaded content items.

      Each of the requested SNS content item is then sent to the requesting client as the CONTENT_DOWNLOAD event that belongs to the CMSNSEvent class, and that can be caught in the client event handler. The CONTENT_DOWNLOAD event includes fields as below:

      CMSNSEvent.CONTENT_DOWNLOAD event
      Event type CMInfo.CM_SNS_EVENT
      Event ID CMSNEEvent.CONTENT_DOWNLOAD
      Event field Get method
      Requester name CMSNSEvent.getUserName()
      Requested content offset CMSNSEvent.getContentOffset()
      Content ID CMSNSEvent.getContentID()
      Written date and time of the content CMSNSEvent.getDate()
      Writer name of the content CMSNSEvent.getWriterName()
      Text message of the content CMSNSEvent.getMessage()
      Number of attachments CMSNSEvent.getNumAttachedFiles()
      Content ID to which this message replies (0 for no reply) CMSNSEvent.getReplyOf()
      Level of disclosure of the content
      0: open to public
      1: open only to friends
      2: open only to bi-friends
      3: private       		CMSNSEvent.getLevelOfDisclosure()
      List of attached file names CMSNSEvent.getFileNameList()

      In most cases, the server sends multiple CONTENT_DOWNLOAD events due to the corresponding number of SNS messages, and it sends the CONTENT_DOWNLOAD_END event of CMSNSEvent as the end signal of current download. This event contains a field that is the number of downloaded messages. A client event handler can catch this event, and the client can send another download request by updating the offset parameter with the number of previously downloaded messages. The detailed event fields of the CONTENT_DOWNLOAD_END event is described below.

      CMSNSEvent.CONTENT_DOWNLOAD_END event
      Event type CMInfo.CM_SNS_EVENT
      Event ID CMSNSEvent.CONTENT_DOWNLOAD_END
      Event field Get method
      User name CMSNSEvent.getUserName()
      Offset CMSNSEvent.getContentOffset()
      Content ID CMSNSEvent.getContentID()
      Number of downloaded items CMSNSEvent.getNumContents()
      Parameters:
      strWriter - - the name of the writer whose content list will be downloaded.
      The client can designate a specific writer name or a friend group. If the parameter value is a specific user name, the client downloads only content that was uploaded by the specified name and that is accessible by the requester. If the parameter value is "CM_MY_FRIEND", the client downloads content that was uploaded by the requester's friends. If the parameter is "CM_BI_FRIEND", the client downloads content that was uploaded by the requester's bi-friends. If the "strWriter" parameter is an empty string (""), the client does not specify a writer name and it downloads all content that the requester is eligible to access.
      nOffset - - the offset from the beginning of the requested content list.
      The client can request to download some number of SNS messages starting from the nOffset-th most recent content. The nOffset value is greater than or equal to 0. The requested content list is sorted in reverse chronological order (in reverse order of uploading time). If the searched content list has 5 items, they have index number starting with 0. The first item (index 0) is the most recent content, the second item (index 1) is the second most recent one, and so on.
      See Also:

    • requestNextSNSContent

      public void requestNextSNSContent()
      Requests to download the next list of SNS content.

      This method requests the next list after the last download request of SNS content. If this method is called without any previous download request, it requests the most recent list of SNS content, which is the same as the result of requestSNSContent(String, int).
      If there is no more next list of SNS content, the server sends the CONTENT_DOWNLOAD_END event of CMSNSEvent without sending the CONTENT_DOWNLOAD event.

      See Also:

    • requestPreviousSNSContent

      public void requestPreviousSNSContent()
      Requests to download the previous list of SNS content.

      This method requests the previous list before the last download request of SNS content. If this method is called without any previous download request, it requests the most recent list of SNS content, which is the same as the result of requestSNSContent(String, int).
      If there is no more previous list of SNS content, the server sends the CONTENT_DOWNLOAD_END event of CMSNSEvent without sending the CONTENT_DOWNLOAD event.

      See Also:

    • requestSNSContentUpload

      public void requestSNSContentUpload(String user, String message, int nNumAttachedFiles, int nReplyOf, int nLevelOfDisclosure, ArrayList<String> filePathList)
      Uploads SNS content.
      A client can call this method to upload a message to the default server.

      If the server receives the content upload request, it stores the requested message with the user name, the index of the content, the upload time, the number of attachments, the reply ID, and the level of disclosure. If the content has attached files, the client separately transfers them to the server. After the upload task is completed, the server sends the CONTENT_UPLOAD_RESPONSE event of CMSNSEvent to the requesting client so that the client handler can catch the result of the request. The detailed event fields of the CONTENT_UPLOAD_RESPONSE event is described below:

      CMSNSEvent.CONTENT_UPLOAD_RESPONSE event
      Event type CMInfo.CM_SNS_EVENT
      Event ID CMSNEEvent.CONTENT_UPLOAD_RESPONSE
      Event field Get method
      Return code CMSNSEvent.getReturnCode()
      Content ID CMSNSEvent.getContentID()
      Date and time CMSNSEvent.getDate()
      User name CMSNSEvent.getUserName()
      Parameters:
      user - - the name of a user who uploads a message
      message - - the text message
      nNumAttachedFiles - - the number of attached files in this message
      The value of nNumAttachedFiles must be the same as the number of elements in a given file path list as the last parameter, filePathList.
      nReplyOf - - an ID (greater than 0) of content to which this message replies
      If the value is 0, it means that the uploaded content is not a reply but an original one.
      nLevelOfDisclosure - - the level of disclosure (LoD) of the uploaded content
      CM provides four levels of disclosure of content from 0 to 3. LoD 0 is to open the uploaded content to public. LoD 1 allows only users who added the uploading user as friends to access the uploaded content. LoD 2 allows only bi-friends of the uploading user to access the uploaded content. (Refer to the friend management section for details of different friend concepts.) LoD 3 does not open the uploaded content and makes it private.
      filePathList - - the list of attached files
      See Also:

    • requestAttachedFileOfSNSContent

      public boolean requestAttachedFileOfSNSContent(String strFileName)
      Requests an attached file of SNS content.

      The client can request to download a file that is attached to a downloaded SNS content item from the server.
      After the client request to download SNS content by the requestSNSContent(String, int) method, all attached files are automatically downloaded from the server. If an attached file is not available at the server, only the file name is downloaded so that the client can separately request such a file from the server later.

      If the server is requested to download an attached file, it sends the RESPONSE_ATTACHED_FILE event of the CMSNSEvent. The client event handler can catch this event, and can figure out the result of the request by getting the return code. If the return code is 1, the requested file is available at the server, and the server separately sends the requested file to the client using the CMStub.pushFile(String, String) method. If the return code is 0, the requested file does not exist at the server.
      The detailed event fields of the RESPONSE_ATTACHED_FILE event are described below:

      CMSNSEvent.RESPONSE_ATTACHED_FILE event
      Event type CMInfo.CM_SNS_EVENT
      Event ID CMSNSEvent.RESPONSE_ATTACHED_FILE
      Event field Get method Description
      User name CMSNSEvent.getUserName() The requesting user name
      Content ID CMSNSEvent.getContentID() The ID of the SNS content that attached the requested file
      Writer name CMSNSEvent.getWriterName() The writer name of the SNS content
      File name CMSNSEvent.getFileName() The name of the attached file
      Return code CMSNSEvent.getReturnCode() The request result. If the value is 1, the requested file will be delivered to the client. If the value is 0, the server does nothing further for the request.
      Parameters:
      strFileName - - the requested file name
      The list of attached file names can be got in the CONTENT_DOWNLOAD event of CMSNSEvent that is sent from the server. After the client event handler catch this event and get the list of attached file names, it can choose a file name that needs to separately download from the server.
      Returns:
      true if the request is successfully sent, or false otherwise
      See Also:

    • requestAttachedFileOfSNSContent

      public void requestAttachedFileOfSNSContent(int nContentID, String strWriterName, String strFileName)
      Requests an attached file of SNS content.

      The detailed information about the request for an attached file can be found in the requestAttachedFileOfSNSContent(String) method.

      Parameters:
      nContentID - - the ID of SNS content to which the requested file is attached
      strWriterName - - the name of a requesting user
      strFileName - - the requested file name
      See Also:

    • accessAttachedFileOfSNSContent

      public boolean accessAttachedFileOfSNSContent(String strFileName)
      Informs the server that the attached file has been accessed by the client.

      The client can call this method to report its access history of an attached file to the server. The access report is sent to the server as the ACCESS_ATTACHED_FILE event of the CMSNSEvent. If the server receives the event, it can use the access information for the analysis of the history of client behavior. The server event handler can catch the event.

      The detailed event fields of the ACCESS_ATTACHED_FILE event are described below:

      CMSNSEvent.ACCESS_ATTACHED_FILE event
      Event type CMInfo.CM_SNS_EVENT
      Event ID CMSNSEvent.ACCESS_ATTACHED_FILE
      Event field Get method Description
      User name CMSNSEvent.getUserName() The name of the file-accessing user
      Content ID CMSNSEvent.getContentID() ID of the SNS content of which attached file is accessed
      Writer name CMSNSEvent.getWriterName() The writer name of the SNS content of which attached file is accessed
      Attached file name CMSNSEvent.getFileName() The name of an attached file that the user accessed
      Parameters:
      strFileName - - the name of an attached file that the user accessed
      Returns:
      true if the file access information is successfully sent to the server and if the corresponding SNS content is found at the client. Otherwise, the return value is false.
      See Also:

    • accessAttachedFileOfSNSContent

      public void accessAttachedFileOfSNSContent(int nContentID, String strWriterName, String strFileName)
      Informs the server that the attached file has been accessed by the client.

      The detailed information about the access report of an attached file to the server can be found in the accessAttachedFileOfSNSContent(String) method.

      Parameters:
      nContentID - - the ID of the SNS content of which attached file is accessed
      strWriterName - - the writer name of the SNS content of which attached file is accessed
      strFileName - - the name of an attached file that the user accessed
      See Also:

    • requestServerInfo

      public void requestServerInfo()
      Requests new additional server information from the default server.

      When the default server registers an additional server, it then notifies clients of the new server information. If a client is a late comer to the CM network, it can also explicitly request the information of additional servers from the default server.
      In any of the above two cases, the default server sends the NOTIFY_SERVER_INFO event of the CMMultiServerEvent class. This event contains the list of additional server information such as a server name, address, port number, and UDP port number. The detailed event fields of the NOTIFY_SERVER_INFO event is described below.

      CMMultiServerEvent.NOTIFY_SERVER_INFO event
      Event typeCMInfo.CM_MULTI_SERVER_EVENT
      Event IDCMMultiServerEvent.NOTIFY_SERVER_INFO
      Event fieldField data typeField definitionGet method
      Number of serversintNumber of additional serversgetServerNum()
      Server listVector<CMServerInfo>List of additional server information getServerInfoList()

      When the default server deletes an additional server by the deregistration request, it then sends the NOTIFY_SERVER_LEAVE event to clients. The event fields of the event are described below.

      CMMultiServerEvent.NOTIFY_SERVER_LEAVE event
      Event typeCMInfo.CM_MULTI_SERVER_EVENT
      Event IDCMMultiServerEvent.NOTIFY_SERVER_LEAVE
      Event fieldField data typeField definitionGet method
      Server nameStringName of an additional server that leaves the CM network getServerName()

    • connectToServer

      public boolean connectToServer(String strServerName)
      Connects to a CM server.

      If the CM network has multiple servers (the default server and additional servers), a CM client can connect to these servers by specifying a server name as the parameter. Connection to an additional server is made with an additional TCP channel created.

      Parameters:
      strServerName - - the server name
      Returns:
      true if the connection is successfully established; or false otherwise.
      See Also:

    • disconnectFromServer

      public boolean disconnectFromServer(String strServerName)
      Disconnects from a CM server.

      If the CM network has multiple servers (the default server and additional servers), a CM client can disconnect from these servers by specifying a server name as the parameter.

      Parameters:
      strServerName - - the server name
      Returns:
      true if the connection is successfully disconnected; or false otherwise.
      See Also:

    • loginCM

      public boolean loginCM(String strServer, String strUser, String strPasswd)
      Logs in to a CM server.

      If the CM network has multiple servers (the default server and additional servers), a CM client can log in to these servers by specifying a server name.
      The login process to an additional CM server is the almost same as that to the default server with the loginCM(String, String) method. Different part is that the login to an additional server requires the target server name, and that the multiple-server-related CM event is the CMMultiServerEvent class instead of the CMSessionEvent. Each event ID of the CMMultiServerEvent is preceded by the "ADD_" and the remaining ID word and its role is the same as that of the CMSessionEvent class. Event fields of the CMMultiServerEvent event is also the same as those of the CMSessionEvent except an additional field, the server name.

      Parameters:
      strServer - - the server name
      strUser - - the user name
      strPasswd - - the password
      Returns:
      true if the request is successfully sent to the server; false otherwise.
      See Also:

    • logoutCM

      public boolean logoutCM(String strServer)
      Logs out from a CM server.

      If the CM network has multiple servers (the default server and additional servers), a CM client can log from one of these servers by specifying a server name.
      The logout process from an additional CM server is the almost same as that from the default server with the logoutCM() method. Different part is that the logout from an additional server requires the target server name, and that the multiple-server-related CM event is the CMMultiServerEvent class instead of the CMSessionEvent. Each event ID of the CMMultiServerEvent is preceded by the "ADD_" and the remaining ID word and its role is the same as that of the CMSessionEvent class. Event fields of the CMMultiServerEvent event is also the same as those of the CMSessionEvent except an additional field, the server name.

      Parameters:
      strServer - - the server name
      Returns:
      true if successfully sent the logout request, false otherwise.
      See Also:

    • requestSessionInfo

      public boolean requestSessionInfo(String strServerName)
      Requests available session information from a CM server.

      If the CM network has multiple servers (the default server and additional servers), a CM client can request session information from one of these servers by specifying a server name.
      The session-information-request process with an additional CM server is the almost same as that with the default server using the requestSessionInfo() method. Different part is that the request from an additional server requires the target server name, and that the multiple-server-related CM event is the CMMultiServerEvent class instead of the CMSessionEvent. Each event ID of the CMMultiServerEvent is preceded by the "ADD_" and the remaining ID word and its role is the same as that of the CMSessionEvent class. Event fields of the CMMultiServerEvent event is also the same as those of the CMSessionEvent except an additional field, the server name.

      Parameters:
      strServerName - - the server name
      Returns:
      true if the request is successfully sent to the server; false otherwise.
      See Also:

    • joinSession

      public boolean joinSession(String strServer, String strSession)
      Joins a session in a CM server.

      If the CM network has multiple servers (the default server and additional servers), a CM client can join a session in one of these servers by specifying a server name.
      The session-join process with an additional CM server is the almost same as that with the default server using the joinSession(String) method. Different part is that the request from an additional server requires the target server name, and that the multiple-server-related CM event is the CMMultiServerEvent class instead of the CMSessionEvent. Each event ID of the CMMultiServerEvent is preceded by the "ADD_" and the remaining ID word and its role is the same as that of the CMSessionEvent class. Event fields of the CMMultiServerEvent event is also the same as those of the CMSessionEvent except an additional field, the server name.

      Parameters:
      strServer - - the server name
      strSession - - the session name
      Returns:
      true if the request is successful; false otherwise.
      See Also:

    • leaveSession

      public boolean leaveSession(String strServer)
      Leaves the current session in a CM server.

      If the CM network has multiple servers (the default server and additional servers), a CM client can leave the current session in one of these servers by specifying a server name.
      The session-leave process in an additional CM server is the almost same as that in the default server using the leaveSession() method. Different part is that the request from an additional server requires the target server name, and that the multiple-server-related CM event is the CMMultiServerEvent class instead of the CMSessionEvent. Each event ID of the CMMultiServerEvent is preceded by the "ADD_" and the remaining ID word and its role is the same as that of the CMSessionEvent class. Event fields of the CMMultiServerEvent event is also the same as those of the CMSessionEvent except an additional field, the server name.

      Parameters:
      strServer - - the server name
      Returns:
      true if successfully sent the leave-session request, false otherwise.
      See Also:

    • registerUser

      public void registerUser(String strName, String strPasswd)
      Registers a user to the default server.

      A user can be registered to CM by the registerUser method of the CM client stub. If a CM client is connected to the default server, it can call this method. CM uses the registered user information for the user authentication when a user logs in to the default server.

      Whether the registration request is successful or not is set to a return code of a reply session event, CMSessionEvent.REGISTER_USER_ACK. If the request is successful, the reply event also contains the registration time at the server.

      Parameters:
      strName - - the user name
      strPasswd - - the password

    • deregisterUser

      public void deregisterUser(String strName, String strPasswd)
      Deregisters a user from the default server.

      A user can cancel his/her registration from CM by the deregisterUser method of the CM client stub. If a client is connected to the default server, it can call this method. When requested, CM removes the registered user information from the CM DB.
      Whether the deregistration request is successful or not is set to a return code of a reply session event, CMSessionEvent.DEREGISTER_USER_ACK.

      Parameters:
      strName - - the user name
      strPasswd - - the password

    • findRegisteredUser

      public void findRegisteredUser(String strName)
      Finds a registered user.

      A user can search for another user by the findRegisteredUser method of the CM client stub. If a client is connected to the default server, it can call this method. When requested, CM provides the basic profile of the target user such as a name and registration time.
      Whether the requested user is found or not is set to a return code of a reply session event, CMSessionEvent.FIND_REGISTERED_USER_ACK.

      Parameters:
      strName - - the user name

    • getGroupMembers

      public CMMember getGroupMembers()
      Gets current group members in the default server.

      A CM client can call this method only if it logs in to the default server.

      Returns:
      group members.

    • addNewFriend

      public void addNewFriend(String strFriendName)
      Adds a new friend user.

      A client can add a user as its friend only if the user name has been registered to CM. When the default server receives the request for adding a new friend, it first checks if the friend is a registered user or not. If the friend is a registered user, the server adds it to the friend table of the CM DB as a friend of the requesting user. Otherwise, the request fails. In any case, the server sends the ADD_NEW_FRIEND_ACK event with a result code to the requesting client so that it can figure out the request result. The detailed information of the ADD_NEW_FRIEND_ACK event is described below.

      CMSNSEvent.ADD_NEW_FRIEND_ACK event
      Event typeCMInfo.CM_SNS_EVENT
      Event IDCMSNSEvent.ADD_NEW_FRIEND_ACK
      Event fieldField data typeField definitionGet method
      Return codeint Result of the request
      1: succeeded
      0: failed       		getReturnCode()
      User nameStringRequester user namegetUserName()
      Friend nameStringFriend namegetFriendName()
      Parameters:
      strFriendName - - the friend name
      See Also:

    • removeFriend

      public void removeFriend(String strFriendName)
      Removes a friend.

      When the default server receives the request for deleting a friend, it searches for the friend of the requesting user. If the friend is found, the server deletes the corresponding entry from the friend table. Otherwise, the request fails. The result of the request is sent to the requesting client as the REMOVE_FRIEND_ACK event with a result code. The detailed information of the REMOVE_FRIEND_ACK event is described below.

      CMSNSEvent.REMOVE_FRIEND_ACK event
      Event typeCMInfo.CM_SNS_EVENT
      Event IDCMSNSEvent.REMOVE_FRIEND_ACK
      Event fieldField data typeField definitionGet method
      Return codeint Result of the request
      1: succeeded
      0: failed       		getReturnCode()
      User nameStringRequester user namegetUserName()
      Friend nameStringFriend namegetFriendName()
      Parameters:
      strFriendName - - the friend name
      See Also:

    • requestFriendsList

      public void requestFriendsList()
      Requests to retrieve current friends list of this client.

      Different SNS applications use the concept of a friend in different ways. In some applications, a user can add another user in his/her friend list without the agreement of the target user. In other applications, a user can add a friend only if the other user accepts the friend request. CM supports such different policies of the friend management by methods that request different user lists.
      The requestFriendsList method requests the list of users whom the requesting user adds as his/her friends regardless of the acceptance of the others.
      The requestFriendRequestersList() method requests the list of users who add the requesting user as a friend, but whom the requesting user has not added as friends yet.
      The requestBiFriendsList() method requests the list of users who add the requesting user as a friend and whom the requesting user adds as friends.

      When the default server receives the request for friends, requesters, or bi-friends from a client, it sends corresponding user list as the RESPONSE_FRIEND_LIST, RESPONSE_FRIEND_REQUESTER_LIST, or RESPONSE_BI_FRIEND_LIST event to the requesting client. The three events have the same event fields as described below. One of the event fields is the friend list, but the meaning of the list is different according to an event ID. The friend list contains a maximum of 50 user names. If the total number exceeds 50, the server then sends the event more than once.

      CMSNSEvent.RESPONSE_FRIEND_LIST, RESPONSE_FRIEND_REQUESTER_LIST, RESPONSE_BI_FRIEND_LIST events
      Event typeCMInfo.CM_SNS_EVENT
      Event ID CMSNSEvent.RESPONSE_FRIEND_LIST
      CMSNSEvent.RESPONSE_FRIEND_REQUESTER_LIST
      CMSNSEvent.RESPONSE_BI_FRIEND_LIST
      Event fieldField data typeField definitionGet method
      User nameStringRequester user namegetUserName()
      Total number of friendsintTotal number of requested friends getTotalNumFriends()
      Number of friendsintNumber of requested friends in this event getNumFriends()
      Friend listArrayList<String>List of requested friend names getFriendList()
      See Also:

    • requestFriendRequestersList

      public void requestFriendRequestersList()
      Requests to retrieve current friend-requesters list of this client.

      The detailed information is described in the requestFriendsList() method.

      See Also:

    • requestBiFriendsList

      public void requestBiFriendsList()
      Requests to retrieve current bi-friends list of this client.

      The detailed information is described in the requestFriendsList() method.

      See Also:

    • getCurrentChannelInfo

      public String getCurrentChannelInfo()
      gets the string representation of current channels information.

      This method overrides the CMStub.getCurrentChannelInfo() method. It firstly calls the parent method to get the current datagram channel information, and then also gets the current blocking/non-blocking socket channel mostly to servers.

      Overrides:
      getCurrentChannelInfo in class CMStub
      Returns:
      string of current channels information if successful, or null otherwise.
      See Also:

    • startFileSync

      public boolean startFileSync(CMFileSyncMode mode)
      start file synchronization.

      CM supports simple file synchronization (file sync) functionality between a client and a server. When the client starts the file sync, files in the client directory and files in the server directory are synchronized. If the client adds a new file or modifies an existing file, the updated file is also synchronized with the corresponding server file.

      When the file sync is completed, the server sends a CMFileSyncEvent to the client. CMFileSyncEvent is an abstract class that is a parent of all specific file sync events. For the file sync completion, the server actually sends a CMFileSyncEventCompleteFileSync event. The client can catch the event to check when the file sync is completed.

      Parameters:
      mode - file sync mode. (CMFileSyncMode.MANUAL, CMFileSyncMode.AUTO)

      The MANUAL mode is the manual file mode change mechanism, and it is the same as MANUAL in the FILE_SYNC_MODE field of the CM client configuration file. In the MANUAL mode, CM starts the file sync with manual file mode change mechanism when the client logs in to the server. In the manual file mode change mechanism, file mode can be changed to local or online mode by the user request. The AUTO mode is the active file mode change mechanism, and it is the same as AUTO in the FILE_SYNC_MODE field of the CM client configuration file. In the AUTO mode, CM starts the file sync with active file mode change mechanism when the client logs in to the server. In the active file mode change mechanism, CM actively changes the file mode of files in the synchronization directory according to directory activation ratio.

      Returns:
      true if successfully file sync started; false otherwise.
      See Also:

    • stopFileSync

      public boolean stopFileSync()
      stops file synchronization.

      This method terminates all the monitoring threads for synchronization related tasks.

      Returns:
      true if the file sync successfully stops. If the file sync cannot stop or any monitoring thread cannot terminate, the method returns false.
      See Also:

    • requestFileSyncOnlineMode

      public boolean requestFileSyncOnlineMode(File[] files)
      requests to change file mode of synchronization to online mode.

      In the file synchronization service, the client can change the file mode of the files in the synchronization directory. The file mode is assumed to be the local mode or the online mode. In the online mode, file content exists only in the remote storage of the server. The local storage of the client maintains only file attributes, and has no file content. Since the file data does not exist on the client, the online mode has the advantage of saving the local storage space. However, when a client tries to access an online mode file, it should first download the original file data from the server, which increases the file access delay. Therefore, the online mode is used to save the client's local storage space.

      Note that the true return value does not mean that CM completes to change the files to the online mode. To check the completion of the file mode change request, the client should catch the file sync completion event (CMFileSyncEventCompleteFileSync) from the server.

      Parameters:
      files - an array of requested local mode files
      If a file is already online mode, CM ignores such file in the file mode change process.
      Returns:
      true if the file mode change request is successfully delivered to CM; false otherwise.
      See Also:

    • requestFileSyncLocalMode

      public boolean requestFileSyncLocalMode(File[] files)
      requests to change file mode of synchronization to local mode.

      In the local mode, file data exists in both the client's local storage and the server's remote storage, and both files are synchronized. The client can directly access the local mode file to read or update it. As soon as the local mode file is updated, the server-side file is also synchronized to reflect the updated content.

      Note that the true return value does not mean that CM completes to change the files to the local mode. To check the completion of the file mode change request, the client should catch the file sync completion event (CMFileSyncEventCompleteFileSync) from the server.

      Parameters:
      files - an array of requested online mode files
      If a file is already local mode, CM ignores such file in the file mode change process.
      Returns:
      true if the file mode change request is successfully delivered to CM; false otherwise.
      See Also:

    • getOnlineModeFiles

      public List<Path> getOnlineModeFiles()
      gets a list of online mode files in the synchronization home directory.

      The client can get the synchronization home directory by calling getFileSyncHome().

      Returns:
      a list of online mode files.
      If the client has wrong system type, does not log in to the server, or the file sync mode is OFF, the method returns null.
      See Also:

    • getLocalModeFiles

      public List<Path> getLocalModeFiles()
      gets a list of local mode files in the synchronization home directory.

      The client can get the synchronization home directory by calling getFileSyncHome().

      Returns:
      a list of local mode files.
      If the client has wrong system type, does not log in to the server, or the file sync mode is OFF, the method returns null.
      See Also:

    • getCurrentFileSyncMode

      public CMFileSyncMode getCurrentFileSyncMode()
      gets a current file synchronization mode.
      Returns:
      current file synchronization mode.
      CMFileSyncMode is an enum object that has three values: OFF, MANUAL, and AUTO. The value is the same as the FILE_SYNC_MODE field of the client CM configuration file (cm-client.conf). If the client does not start the file sync, this method returns OFF. If the client starts the file sync with the manual file mode change mechanism, this method returns MANUAL. If the client starts the file sync with the active file mode change mechanism, this method returns AUTO.
      See Also:

    • getFileSyncHome

      public Path getFileSyncHome()
      gets the file synchronization home directory.

      To use the file sync, the client uses a designated synchronization directory in the transferred file home. The transferred file home is set in the FILE_PATH field of CM client configuration file (cm-client.conf). CM specifies the name of synchronization directory as “FileSyncHome”. Therefore, if the transferred file home is “./client-file-path”, then the synchronization home directory is “./client-file-path/FileSyncHome”. When we start the file sync at the first time, CM creates the empty synchronization home directory. If we add a new file in the sync directory, it is synchronized with the server.

      Returns:
      the file synchronization home directory.
      This method returns null instead of the synchronization home directory if the client has wrong system type (“SERVER”), or has not logged in to the server.
      See Also: